# SmartTube Leanback UI Customization: A Complete Guide for Android TV Developers

> Master SmartTube Leanback UI customization. Learn to modify theme resources, extend LeanbackActivity, and override attributes for a personalized Android TV experience.

- Repository: [Yuriy L/SmartTube](https://github.com/yuliskov/SmartTube)
- Tags: how-to-guide
- Published: 2026-09-14

---

**You can fully customize SmartTube's Android TV interface by modifying theme resources in [`styles.xml`](https://github.com/yuliskov/SmartTube/blob/main/styles.xml), extending the `LeanbackActivity` base class, and overriding Leanback library attributes such as `imageCardViewStyle` and `primaryColor`.**

SmartTube builds its 10-foot user interface on the Android Leanback support library, providing a TV-optimized experience through the `yuliskov/SmartTube` repository. The architecture relies on a centralized theming system where XML resources and Java base classes work together to render browsing, playback, and guided-step screens. Mastering SmartTube Leanback UI customization requires understanding how `LeanbackActivity` orchestrates background managers, adapters, and theme attributes across the application.

## Core Architecture and Base Classes

### The LeanbackActivity Foundation

At the heart of every screen lies **[`LeanbackActivity.java`](https://github.com/yuliskov/SmartTube/blob/main/LeanbackActivity.java)**, located in [`smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/common/LeanbackActivity.java`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/common/LeanbackActivity.java). This abstract base class initializes essential Leanback components including the `BackgroundManager` for wallpaper switching and the `LeanbackPlayerAdapter` for media controls.

Any activity extending this class automatically inherits the default Leanback theming structure. For example, `PlaybackActivity`, `SearchTagsActivity`, and `WebBrowserActivity` all derive from `LeanbackActivity`, ensuring consistent navigation patterns and visual styling across the app.

### Theme Inheritance and Color Palettes

SmartTube defines its visual identity through a hierarchy of XML themes extending standard Leanback parents. The core themes include:

- **`App.Theme.Leanback.Player`** – Controls the playback overlay UI
- **`App.Theme.Leanback.Browse`** – Governs the content browsing grids and headers  
- **`App.Theme.Leanback.GuidedStep`** – Styles the wizard-like configuration screens

Specific color variants such as **Blue**, **Red**, **DarkGrey**, and **OLED** inherit from these base themes and override attributes like `background`, `primaryColor`, and `preferenceTheme` to create distinct visual modes.

## Customizing Visual Styles

### Modifying Color Schemes in styles.xml

To change the global color palette, edit [`smarttubetv/src/main/res/values/styles.xml`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/res/values/styles.xml). Locate the theme definition you wish to modify—such as `App.Theme.Leanback.Blue`—and override the color attributes:

```xml
<style name="App.Theme.Leanback.Blue" parent="Theme.Leanback.Browse">
    <item name="primaryColor">@color/teal_200</item>
    <item name="background">@color/teal_900</item>
    <item name="preferenceTheme">@style/App.Preference.Theme</item>
</style>

```

These changes propagate immediately to all fragments because the `LeanbackActivity` inflates views using these theme resources at runtime.

### Creating Custom Card Layouts

Video cards, tag cards, and loading cards obtain their styling from **`LeanbackTheme`** attributes. The system retrieves the active style programmatically using the `TypedArray` pattern found in [`VideoCardView.java`](https://github.com/yuliskov/SmartTube/blob/main/VideoCardView.java):

```java
TypedArray a = context.obtainStyledAttributes(R.styleable.LeanbackTheme);
int styleRes = a.getResourceId(R.styleable.LeanbackTheme_imageCardViewStyle, 0);
a.recycle();

```

To apply a custom card appearance, define a new style in [`smarttubetv/src/main/res/values/themes.xml`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/res/values/themes.xml) (or [`themes_old.xml`](https://github.com/yuliskov/SmartTube/blob/main/themes_old.xml)) and reference it in your main theme:

```xml
<style name="Widget.Custom.VideoCard" parent="Widget.Leanback.ImageCardView">
    <item name="cardBackgroundColor">@color/dark_gray</item>
    <item name="titleTextAppearance">@style/TextAppearance.Custom.CardTitle</item>
</style>

<style name="App.Theme.Leanback.Browse">
    <item name="leanbackTheme_imageCardViewStyle">@style/Widget.Custom.VideoCard</item>
</style>

```

For granular layout control, modify the XML files in `smarttubetv/src/main/res/layout/`, such as [`text_badge_image_view.xml`](https://github.com/yuliskov/SmartTube/blob/main/text_badge_image_view.xml), which defines how text badges render on image cards using `TextAppearance.Leanback.ImageCardView.Content`.

## Runtime UI Modifications

### Switching Themes Programmatically

SmartTube supports dynamic theme changes without recompiling the application. To switch themes at runtime based on user preferences, call `setTheme()` before `recreate()`:

```java
public void switchToDarkTheme() {
    setTheme(R.style.App_Theme_Leanback_OLED_Browse);
    recreate(); // Forces Activity reload with new resources
}

```

This pattern works because `LeanbackActivity` re-inflates all UI components using the newly set theme resources, including the `GuidedStepFragment` styles defined in layouts like [`guidedstep_second_guidance.xml`](https://github.com/yuliskov/SmartTube/blob/main/guidedstep_second_guidance.xml).

### Customizing Playback Components

The playback interface relies on [`PlaybackFragment.java`](https://github.com/yuliskov/SmartTube/blob/main/PlaybackFragment.java) located in `smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/playback/`. To override subtitle rendering or control positioning, access the view hierarchy after the fragment creates its Leanback player adapter:

```java
// In PlaybackFragment.java
mLeanbackSubtitles = root.findViewById(R.id.my_custom_subtitles);

```

You can also customize the guided-step icons by modifying the `Widget.Example.Leanback.*GuidanceIconStyle` styles referenced in [`guidedstep_second_guidance.xml`](https://github.com/yuliskov/SmartTube/blob/main/guidedstep_second_guidance.xml) and related layout files.

## Key Files for UI Customization

Understanding the location of critical resources accelerates the customization workflow:

- **[`LeanbackActivity.java`](https://github.com/yuliskov/SmartTube/blob/main/LeanbackActivity.java)** – Base activity supplying `BackgroundManager` and `LeanbackPlayerAdapter` 
- **[`styles.xml`](https://github.com/yuliskov/SmartTube/blob/main/styles.xml)** – Primary theme definitions and color palette variants
- **[`themes_old.xml`](https://github.com/yuliskov/SmartTube/blob/main/themes_old.xml)** – Custom widget styles for titles, rows, and guidance icons
- **[`VideoCardView.java`](https://github.com/yuliskov/SmartTube/blob/main/VideoCardView.java)** – Card view implementation that consumes `LeanbackTheme` attributes
- **[`PlaybackFragment.java`](https://github.com/yuliskov/SmartTube/blob/main/PlaybackFragment.java)** – Playback UI integration point for subtitles and controls
- **[`guidedstep_second_guidance.xml`](https://github.com/yuliskov/SmartTube/blob/main/guidedstep_second_guidance.xml)** – Layout template for guided-step icon styling
- **[`text_badge_image_view.xml`](https://github.com/yuliskov/SmartTube/blob/main/text_badge_image_view.xml)** – Badge text appearance configuration

## Summary

- **SmartTube** implements its Android TV interface through the Leanback library, centered around the `LeanbackActivity` base class located in [`smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/common/LeanbackActivity.java`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/common/LeanbackActivity.java).
- **Visual customization** occurs primarily in [`smarttubetv/src/main/res/values/styles.xml`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/res/values/styles.xml) by overriding theme attributes like `primaryColor` and `background`.
- **Card appearances** are controlled through `LeanbackTheme` attributes such as `imageCardViewStyle`, which are resolved at runtime via `TypedArray` lookups.
- **Runtime theme switching** is achieved by calling `setTheme()` followed by `recreate()` in activities extending `LeanbackActivity`.
- **Playback components** can be modified through [`PlaybackFragment.java`](https://github.com/yuliskov/SmartTube/blob/main/PlaybackFragment.java) and associated layout files for subtitles and control overlays.

## Frequently Asked Questions

### How does SmartTube implement the Leanback library for Android TV?

SmartTube extends the Android Support Leanback library through the `LeanbackActivity` base class, which provides essential infrastructure including `BackgroundManager` for wallpaper handling, `LeanbackPlayerAdapter` for media playback controls, and standardized fragment management for browsing and guided steps. This architecture ensures all TV-specific activities share consistent navigation and theming behavior.

### Where are the color themes defined in the SmartTube source code?

Color themes are defined in [`smarttubetv/src/main/res/values/styles.xml`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/res/values/styles.xml), where variants like `App.Theme.Leanback.Blue`, `App.Theme.Leanback.Red`, and `App.Theme.Leanback.OLED` extend `Theme.Leanback.Browse` or related parents. These definitions override specific attributes such as `primaryColor` and `background` to create distinct visual schemes that apply across the entire application interface.

### Can I change the UI theme while the app is running on an Android TV device?

Yes, SmartTube supports runtime theme switching programmatically. By calling `setTheme(R.style.App_Theme_Leanback_OLED_Browse)` followed by `recreate()` within any activity extending `LeanbackActivity`, the application reloads with the new resource set. This pattern allows users to switch between light, dark, and OLED modes without requiring an application restart.

### How do I customize the appearance of video cards in the SmartTube browse interface?

Video card styling is controlled through the `leanbackTheme_imageCardViewStyle` attribute. Define a custom style extending `Widget.Leanback.ImageCardView` in your theme resources, then reference it in your main theme. The `VideoCardView` class retrieves this style at initialization using `context.obtainStyledAttributes(R.styleable.LeanbackTheme)`, ensuring all cards render with your custom background colors, typography, and badges.