tv

API Reference
androidx.tv.foundation
androidx.tv.foundation.lazy.grid
androidx.tv.foundation.lazy.list
androidx.tv.material3

Provides developers with Compose and Material design functionalities in order to write applications for TV

Latest Update	Stable Release	Release Candidate	Beta Release	Alpha Release
January 15, 2025	1.0.0	-	-	1.1.0-alpha01

Declaring dependencies

To add dependencies on tv-foundation and tv-material, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

Groovy

dependencies {
    implementation "androidx.tv:tv-foundation:1.0.0-alpha12"
    implementation "androidx.tv:tv-material:1.1.0-alpha01"
}

Kotlin

dependencies {
    implementation("androidx.tv:tv-foundation:1.0.0-alpha12")
    implementation("androidx.tv:tv-material:1.1.0-alpha01")
}

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

There are no release notes for this artifact.

Tv-Material Version 1.1

Version 1.1.0-alpha01

January 15, 2025

androidx.tv:tv-material:1.1.0-alpha01 is released. Version 1.1.0-alpha01 contains these commits.

API Changes

Change FocusEnterExitScope.cancelFocus() to cancelFocusChange()(I89959)
FocusProperties.enter and FocusProperties.exit have been replaced with onEnter and onExit, respectively,using a receiver scope instead of FocusDirection parameter. (I6e667)

Bug Fixes

Moved CompositingStrategy.OffScreen from Surface to Text for fixing the jittery text while scaling. (I92b15f17)
Fixed broken focus management in Carousel (Ie508b721375)
Surface (non-interactive) has a simplified implementation as compared to the interactive ones. (I7ea545150)

Tv-Material Version 1.0

Version 1.0.0

August 21, 2024

androidx.tv:tv-material:1.0.0 is released. Version 1.0.0 is the first stable release of androidx.tv:tv-material.

Version 1.0.0-rc02

August 7, 2024

androidx.tv:tv-material:1.0.0-rc02 is released. Version 1.0.0-rc02 contains these commits.

Bug Fixes

Fixed Jittery text animation in Surface composable. (3163319)

Version 1.0.0-rc01

July 10, 2024

androidx.tv:tv-material:1.0.0-rc01 is released. Version 1.0.0-rc01 contains these commits.

Version 1.0.0-beta01

May 1, 2024

androidx.tv:tv-material:1.0.0-beta01 is released. Version 1.0.0-beta01 contains these commits.

API Changes

ColorScheme and its utility functions are now stable. (If34fa)
LocalContentColor is now stable (I60ee2)
Typography API is now stable (I088d6)
Shapes APIs are now stable (I0f5f4)
Border API is now stable (I69281)
Glow API is now stable (Iea5f1)
Icon component is now stable (I62c2d)
LocalTextStyles API is now stable (Iaded8)
MaterialTheme API is now stable (I2f541)
Text Component is now stable (Ib9e31)
RadioButton component is now stable (Ia03c8)
Switch component is now stable (I6cea3)
Checkbox components are now stable (I7eafc)
Surface components are now stable (I58758, I04aca)
Renamed NonInteractiveSurfaceDefaults to SurfaceDefaults and NonInteractiveSurfaceColors to SurfaceColors (I0812e)
Selectable Surface now uses “select” terminology instead of “check” because they both have different semantics meaning (I5a206)
NavigationDrawer and NavigationDrawerScope are now stable (I249c1)
NavigationDrawerItem component is now stable (Id6986)
Tab and TabRow components are now stable (I92d92)
Button, OutlinedButton, IconButton, OutlinedIconButton and WideButton components are now stable (Ib4de8)
Card, ClassicCard, CompactCard, WideClassicCard, StandardCardContainer & WideCardContainer components are now stable (I34390)
Renamed StandardCardLayout to StandardCardContainer and WideCardLayout to WideCardContainer (I08883)
Removed CardContainerDefaults.ImageCard and renamed CardDefaults.ContainerGradient to CardDefaults.ScrimBrush (I6adfe). You can make use of Card inplace of CardContainerDefaults.ImageCard in your card containers.
ListItem and DenseListItem are now stable (Idebd9)
ListItemDefaults.ListItemShape, ListItemDefaults.FocusedDisabledBorder & ListItemDefaults.SelectedContainerColorOpacity are now private (I5d533)
Rearranged the ListItem’s parameters & renamed ListItemDefaults.ListItemElevation to ListItemDefaults.TonalElevation (Id6841). headlineContent parameter has been moved to the top of the composable. Earlier, you could make use of Kotlin's trailing lambda syntax to pass the headlineContent. Now, you will have to make use of named parameter syntax to provide the headlineContent.
LocalAbsoluteTonalElevation is now internal (Ibfc65)
The ImmersiveList component has been removed. Check out this sample to learn how to build it yourself. (Id48da)
tv-material components exposing a MutableInteractionSource in their API have been updated to now expose a nullable MutableInteractionSource that defaults to null. There are no semantic changes here: passing null means that you do not wish to hoist the MutableInteractionSource, and it will be created inside the component if needed. Changing to null allows for some components to never allocate a MutableInteractionSource, and allows for other components to only lazily create an instance when they need to, which improves performance across these components. If you are not using the MutableInteractionSource you pass to these components, it is recommended that you pass null instead. It is also recommended that you make similar changes in your own components. (I309b4, b/298048146)
TV Text component's TextAlign parameter is now non-null (Ib73b1, b/299490814)
Introduced a special Unspecified value for TextAlign, TextDirection, Hyphens and LineBreak fields of the ParagraphTextStyle to replace (I4197e, b/299490814)

Behaviour Changes

Default value of the shape parameter for non-interactive Surface has been changed to RectangleShape (I1b859cb)
Some carousel features have been dropped for the beta launch due to necessary APIs being experimental (I0e755d4)
Changing contentColor in Surface no longer animates between states (I436e794f)

Version 1.0.0

Version 1.0.0-alpha12

January 15, 2025

androidx.tv:tv-foundation:1.0.0-alpha12 is released. Version 1.0.0-alpha12 contains these commits.

API Changes

Cleanup lazy layouts from tv-foundation. Refer to 1.0.0-alpha11 release notes to migrate away from tv-foundation lazy layouts. (I2fdd3, b/358913893)

Version 1.0.0-alpha11

July 10, 2024

androidx.tv:tv-foundation:1.0.0-alpha11 is released. Version 1.0.0-alpha11 contains these commits.

API Changes

Tv Lazy Layouts have been deprecated from tv-foundation library. Refer to this ticket to learn how to migrate away from the tv lazy layouts. (I0855f, b/332674072)
PlatformImeOptions is now a concrete class instead of an interface. (If40a4)

Version 1.0.0-alpha10

October 4, 2023

androidx.tv:tv-foundation:1.0.0-alpha10 and androidx.tv:tv-material:1.0.0-alpha10 are released. Version 1.0.0-alpha10 contains these commits.

New Features

Introduced NavigationDrawerItem to be used within NavigationDrawer and ModalNavigationDrawer. (I4b491)
Add baseline profile to tv-foundation library. (2b57fd7)
Add baseline profile to tv-material library. (1711ff5)

API Changes

Renamed NavigationDrawerScope.doesTabRowHaveFocus to NavigationDrawerScope.hasFocus. (I8286b)
Renamed TabRowScope.isActivated to TabRowScope.hasFocus. (Ic4273)

Bug Fixes

Fix compatibility of Carousel with adjacent items that use focus restorer APIs. (7b2a7a4)
Disable glow indication for API_LEVEL below 28 as it is not supported by the OS. (6d3616f)
Fix ANR crash caused by improper item placement in lazy containers when fast scrolling in reverse direction. (642d65c)
Removed background padding in Modal Navigation Drawer. (69965b2)
Fix Scrim in Navigation Drawer to be drawn above background content instead of behind it. (d4bbefb)

Version 1.0.0-alpha09

September 6, 2023

androidx.tv:tv-foundation:1.0.0-alpha09 and androidx.tv:tv-material:1.0.0-alpha09 are released. Version 1.0.0-alpha09 contains these commits.

API Changes

Add ReusableComposition interface for managing lifecycle and reuse of subcompositions. (I812d1, b/252846775)
Sync tv-foundation fork with compose-foundation. (I737c3, b/287011882)
Overload of LazyLayout added, it accepts a lambda of LazyLayoutItemProvider, not a plain object as it was before. The previous overload is deprecated. (I42a5a)
Add TvKeyboardAlignment to allow the developer to configure the on-screen keyboard position through the AndroidImeOptions. (Idb772)
Add rememberCarouselState to remember CarouselState with Saver to TV Compose Material. (Id7275)
Changing the scrimColor: Color parameter to scrimBrush:Brush parameter to allow users to add gradients to the scrim. (I254d4)

Version 1.0.0-alpha08

July 26, 2023

androidx.tv:tv-foundation:1.0.0-alpha08 and androidx.tv:tv-material:1.0.0-alpha08 are released. Version 1.0.0-alpha08 contains these commits.

New Features

Introduce Chip components for Compose for TV material. (I86da4)
Add ListItem component to TV Compose Material. (I3f0b3)
Add DenseListItemcomponent to TV Compose Material. (I536bf)

API Changes

Marked public tv-material APIs as Experimental. (I632e7)
Introduced TabRowScope to share state from TabRow composable with Tab composable and renamed TabColors properties. (Ief587)

Version 1.0.0-alpha07

June 7, 2023

androidx.tv:tv-foundation:1.0.0-alpha07 and androidx.tv:tv-material:1.0.0-alpha07 are released. Version 1.0.0-alpha07 contains these commits.

API Changes

Components’ scale indications now include None to disable scaling. (I50df5)
Added long click support for TV Material Surface, Cards and Buttons. (Id2b89)
CarouselItem and CarouselScope have been removed. Foreground content animation can be achieved in the slide by using Modifier.animateEnterExit from AnimatedContentScope. (Ic038e)
Merged color and contentColor params as colors for TV Material Surface. (Ie69eb)
Introduced RadioButton composable in TV Material. (I08690)
Introduced Switch composable in TV Material. (I45e29)
Introduced Checkbox composable in TV Material. (I6a45a)
Introduced non-interactable Surface in TV Material. (Ic5f85)
Make indications internal. (Ibff82)

Version 1.0.0-alpha06

April 19, 2023

androidx.tv:tv-foundation:1.0.0-alpha06 and androidx.tv:tv-material:1.0.0-alpha06 are released. Version 1.0.0-alpha06 contains these commits.

New Features

Add Material 3 Card implementations optimized for TV.
- Basic Card (I5b701)
- ClassicCard, CompactCard and WideClassicCard (I70471)
- StandardCardLayout and WideCardLayout (I33fae)
Add Material 3 Button implementations optimized for TV.
- Basic Button (I69c11)
- IconButton and OutlinedIconButton (Ib504c)
- WideButton (I4cecf)

API Changes

Renamed CarouselSlide and slideCountin Carousel to CarouselItem and itemCount. (Ie554c)
Renamed forward and backward ContentTransforms to StartToEnd and EndToStart. (Ie554c)

Bug Fixes

Handle back DPAD button when focused on NavigationDrawer. (d654f4)

Version 1.0.0-alpha05

March 22, 2023

androidx.tv:tv-foundation:1.0.0-alpha05 and androidx.tv:tv-material:1.0.0-alpha05 are released. Version 1.0.0-alpha05 contains these commits.

API Changes

Introducing Side Navigation Drawer composable into tv-material. To learn how to use this composable, please refer to the samples. (I12c08)
Introduce Icon composable in TV Material 3 (I72db9)
Introducing Surface composable to tv-material with indications such as Border, Glow and Scale, which can be used to build components that clearly highlight the focused element on the TV screen. (I4a6d8), (Iceea1), (Iee4d4), (I79edf), (Icb376)
Update CarouselItem to CarouselSlide to match the slideCount param name in 'Carousel' API (Ic4299)

Version 1.0.0-alpha04

February 8, 2023

androidx.tv:tv-foundation:1.0.0-alpha04 and androidx.tv:tv-material:1.0.0-alpha04 are released. Version 1.0.0-alpha04 contains these commits.

New Features

In lazy rows, columns and grids, the pivot is overridden, if necessary, to ensure the entire item is brought into view. (11d7e40)
Add customization of tab colors in different states. (21b2925)
Carousel now accepts custom animations for forward and backward manual scrolling. (431494a)

API Changes

Renaming androidx.tv.material to androidx.tv.material3 and flattening package structure under androidx.tv.material3. (I6ca52)
Indicator within Carousel Indicator row is now a slot that can be customized by the developer. (268af2a)
Renamed focusableItem to immersiveListItem. Users will have to manually add focusable() or clickable() modifier along with immersiveListItem (5dd5078)(b/263061052)
Renamed timeToDisplayMillis to autoScrollDurationMillis in Carousel component. (431494a)
CarouselItem is now restricted to use within Carousel's. (431494a)
Carousel now accepts ContentTransforms as the animation definition instead of EnterTransition and ExitTransitions. (431494a)
Introduced PinnableContainer api propagated by lazy lists via a composition local which allows to pin current item. (Ib8881, b/259274257, b/195049010)
Added mainAxisItemSpacing property to TvLazyListLayoutInfo and TvLazyGridLayoutInfo (I37765)

Bug Fixes

Update tab-row to ensure it handles tab-count of 0 or 1 correctly. (I44009), (1c01525), (b/264018028)
Fix focus-search crash when TvLazyColumn contains empty TvLazyRow. (e11b4fe), (b/260299091)
The clickable modifier now works with ImmersiveList. (5dd5078), (b/263061052)
Back key is now handled and used to exit Featured Carousel. (84c138c)
Carousel does not lose focus on multiple fast key-presses. (799489f)
Carousel does not lose focus on long key-presses. (b2cf37e)
Addressed crashes when carousel slide-count changes. (b261247)

Version 1.0.0-alpha03

December 7, 2022

androidx.tv:tv-foundation:1.0.0-alpha03 and androidx.tv:tv-material:1.0.0-alpha03 are released. Version 1.0.0-alpha03 contains these commits.

New Features

TabRow is now available as an experimental API allowing users to add top navigation bars to their apps. Generally, TV devices expect tabs to load when the tab-title is focused on in the tab-row.
TV specific indicators like underline indicator and pill indicator are offered out of the box. Sample usages can be found in tv-samples

Version 1.0.0-alpha02

November 9, 2022

androidx.tv:tv-foundation:1.0.0-alpha02 and androidx.tv:tv-material:1.0.0-alpha02 are released. Version 1.0.0-alpha02 contains these commits.

Bug Fixes

Improved scrolling performance when scrolling through a collection of TvLazyRows/TvLazyColumns by reducing the focus search space.(I723a3)

Version 1.0.0-alpha01

October 5, 2022

androidx.tv:tv-foundation:1.0.0-alpha01 and androidx.tv:tv-material:1.0.0-alpha01 are released. Version 1.0.0-alpha01 contains these commits.

New Features

The first alpha contains early preview implementations of components for TV use cases, including:

Adding modifier scrollableWithPivot to allow non-lazy scrolling containers such as Row, Column, Grid to have the scrolling container scroll the content so that the item-in-focus remains at the same position on the TV screen.
Adding composables TvLazyRow,TvLazyColumn, TvLazyHorizontalGrid, TvLazyVerticalGrid to have the scrolling container scroll the content so that the item-in-focus remains at the same position on the TV screen.
Adding Featured Carousel composable for TV that allows the user to create an auto-scrolling banner carousel.
Adding Immersive List composable for TV that allows the user to create an Immersive Row/Column/Grid that changes the background based on the list-item in focus.

Known issues

When scrolling container gains focus, the first element does not gain focus by default.
Focusing on a TextField does not always open the keyboard or can inhibit focus from moving to other fields.
Scrolling vertically in a LazyColumn containing LazyRows has poor performance.