kmp-compose-tv

Files (1)

• SKILL.md

SKILL.md (first lines)

# Compose for TV

> The Android TV app uses `androidx.tv:tv-foundation` and `androidx.tv:tv-material` for TV-optimized Compose components. These provide built-in D-pad navigation, focus handling, and TV-appropriate interaction patterns.

## Core TV components

### TvLazyRow — horizontal content rails

```kotlin
import androidx.tv.foundation.lazy.list.TvLazyRow
import androidx.tv.foundation.lazy.list.items

TvLazyRow(
    contentPadding = PaddingValues(horizontal = 48.dp),
    horizontalArrangement = Arrangement.spacedBy(16.dp),
) {
    items(contentItems, key = { it.id }) { item ->
        TVCard(
            item = item,
            onItemClick = { /* navigate to detail */ },
            onItemFocused = { /* update hero banner */ },
        )
    }
}
```

**When to use:** Any horizontal scrolling content row — category rails, "continue watching", recommendations.

**Key points:**
- Always provide `key = { it.id }` for stable focus restoration
- `contentPadding` with 48dp horizontal gives breathing room from screen edges
- `Arrangement.spacedBy(16.dp)` for consistent card spacing

### TvLazyColumn — vertical scrollable layout

```kotlin
import androidx.tv.foundation.lazy.list.TvLazyColumn

TvLazyColumn(
    modifier = Modifier.fillMaxWidth().weight(1f),
    contentPadding = PaddingValues(top = 24.dp, bottom = 48.dp),
) {
    categoryList.forEachIndexed { index, (genre, items) ->
        item {
            ContentRow(title = genre, items = items)
        }
    }
}
```

**When to use:** Home screen layout containing multiple rails, settings lists, any vertical scroll.

### Surface (tv-material) — focusable containers

```kotlin
import androidx.tv.material3.Surface
import androidx.tv.material3.ExperimentalTvMaterial3Api
import androidx.tv.material3.ClickableSurfaceDefaults

@OptIn(ExperimentalTvMaterial3Api::class)
Surface(
    onClick = { onItemClick(item) },
    modifier = modifier.width(220.dp).aspectRatio(16f / 9f),
    tonalElevation = if (isFocused) 8.dp else 2.dp,
    colors = ClickableSurfaceDefaults.colors(
        containerColor = Color.Transparent,
        focusedContainerColor = Color.Transparent,
    ),
    shape = ClickableSurfaceDefaults.shape(shape = RoundedCornerShape(8.dp)),
) {
    // Card content
}
```

**Key:** `Surface` from `androidx.tv.material3` (not regular material3) handles focus states natively. It responds to D-pad select without custom click handling.

## Focus management

### FocusRequester — programmatic focus control

```kotlin
val focusRequester = remember { FocusRequester() }

// Apply to the element that should receive initial focus
TvLazyRow {
    items(items) { item ->
        TVCard(
            modifier = if (item == items.first()) {
                Modifier.focusRequester(focusRequester)
            } else Modifier,
        )
    }
}

// Request focus after content loads
LaunchedEffect(items) {
    if (items.isNotEmpty()) {
        focusRequester.requestFocus()
    }
}
```

**When to use:**
- Setting initial focus when a screen loads
- Restoring focus after data refresh
- Moving focus programmatically (e.g., after dialog dismissal)

### onFocusChanged — reacting to focus

```kotlin
Modifier.onFocusChanged { focusState ->
    isFocused = focusState.isFocused
    if (focusState.isFocused) {
        onItemFocused(item)  // e.g., update hero banner
    }
}
```

**Pattern:** The template uses focus changes on cards to drive the hero banner. When a card receives focus, it notifies the parent, which updates the hero image with a debounced crossfade.

From giolaq/tv-build-harness, MIT-0.

More from giolaq/tv-build-harness