Compose for TV is our recommended approach for building Android TV user interfaces. It unlocks all the benefits of Android's Jetpack Compose for your TV apps, making building beautiful and functional UIs for your app much easier. Some specific benefits of using Compose for TV are:
- Flexibility: Compose can be used to create any type of UI, from simple layouts to complex animations. Components work out of the box but can also be customized and styled to fit your app's needs.
- Simplified & Accelerated Development: Compose is compatible with existing code and enables developers to more efficiently build apps with less code.
- Intuitive: Compose uses a declarative syntax that lets you to make changes to your UI, debug, understand and review your code.
If you are unfamiliar with using the Jetpack Compose toolkit, check out the Compose pathway. Many of the development principles for mobile Compose apply to TV as well. See Why Compose for more information about the general advantages of a declarative UI framework. To learn more, also see the Compose for TV samples repository on GitHub.
Compatibility
Compose for TV works on Android TVs with API level 21 or later. Using version 1.0 of Compose for TV requires version 1.3.0 of androidx.compose libraries and Kotlin 1.7.10.
Setup
Using Jetpack Compose on Android TV is similar to using Jetpack Compose for any
other Android project. The main difference is that Compose for TV adds libraries
that offer TV optimized components and make it easier to create user interfaces
tailored to TV. In some cases those components share the same name as their
non-TV counterparts, such as
androidx.tv.material3.Button
and
androidx.compose.material3.Button
.
Jetpack Compose toolkit dependencies
To use Compose for TV, you need to include Jetpack Compose toolkit
dependencies in your app's build.gradle
file as follows:
Kotlin
dependencies { val composeBom = platform("androidx.compose:compose-bom:2024.05.00") implementation(composeBom) // General compose dependencies implementation("androidx.activity:activity-compose:1.9.0") implementation("androidx.compose.ui:ui-tooling-preview") debugImplementation("androidx.compose.ui:ui-tooling") // Compose for TV dependencies val tvCompose = "1.0.0-beta01" implementation("androidx.tv:tv-foundation:$tvCompose") implementation("androidx.tv:tv-material:$tvCompose") }
Groovy
dependencies { def composeBom = platform('androidx.compose:compose-bom:2024.05.00') implementation composeBom // General compose dependencies implementation 'androidx.activity:activity-compose:1.9.0' implementation 'androidx.compose.ui:ui-tooling-preview' debugImplementation 'androidx.compose.ui:ui-tooling' // Compose for TV dependencies def tvCompose = '1.0.0-beta01' implementation 'androidx.tv:tv-foundation:$tvCompose' implementation 'androidx.tv:tv-material:$tvCompose' }
What's different
Use the TV version of APIs wherever possible.
While it is technically possible to use the mobile version of Compose Material,
it is not optimized for the unique style of interactions on Android TV. In
addition, mixing Compose Material with Compose Material from Compose for TV can
result in unexpected behavior. For example, because each library has its own
MaterialTheme
object, there's the possibility of colors, typography, or shapes
being inconsistent if both versions are used.
The following table outlines the dependency differences between TV and Mobile:
TV Dependency (androidx.tv.*) |
Comparison | Mobile Dependency (androidx.compose.*) |
---|---|---|
androidx.tv:tv-material | instead of | androidx.compose.material3:material3 |
androidx.tv:tv-foundation | in addition to | androidx.compose.foundation:foundation |
Additional resources
TV Material Catalog sample
A catalog app that demonstrates how to implement Material Design principles using Compose for TV.JetStream sample
A media streaming app that demonstrates the use of TV Compose with a typical Material app and real-world architecture.Introduction to Compose for TV
This codelab steps through building a video-player app with a catalog-browser screen and a details screen.
Further reading
Explore these guides to learn about building great TV-optimized experiences for: