aldefy/compose-skill / skills/compose-expert
compose-expert
UnverifiedCompose and Compose Multiplatform expert for UI development across Android, Desktop, iOS, and Web. Use whenever the user mentions Compose APIs (@Composable, remember, LaunchedEffect, NavHost, MaterialTheme, LazyColumn, Modifier, recomposition), Compose Multiplatform (commonMain, expect/actual, Res.*, ComposeUIViewController, UIKitView, ComposeViewport), Android TV (tv-material, D-pad, focus, Carousel), Material 3 motion, atomic design systems, design-to-code workflows, Paging 3, or navigation. Activates Review Mode on GitHub PR URLs and review phrases ("review this PR", "what's wrong with this"). Auto-detects Compose projects on session_start. Backed by actual androidx/androidx and JetBrains/compose-multiplatform-core source receipts. See "## When this skill applies" in SKILL.md for the full trigger surface.
references/lists-scrolling.md
View on GitHub# Lists and Scrolling in Jetpack Compose
Efficient list rendering and scrolling are core to responsive mobile UIs. Jetpack Compose provides lazy layouts that compose items on-demand, not all at once.
## LazyColumn and LazyRow
These composables only compose visible items, making them efficient for large lists unlike `Column`/`Row` which compose all children upfront.
### LazyColumn (Vertical Scrolling)
```kotlin
LazyColumn(modifier = Modifier.fillMaxSize()) {
item {
HeaderComposable()
}
items(itemList.size) { index ->
ListItemComposable(itemList[index])
}
item {
FooterComposable()
}
}
```
### LazyRow (Horizontal Scrolling)
```kotlin
LazyRow(modifier = Modifier.fillMaxWidth()) {
items(imageList.size) { index ->
Image(
painter = painterResource(imageList[index]),
contentDescription = null,
modifier = Modifier.width(200.dp)
)
}
}
```
**Key difference from Column/Row:** Items are composed lazily as they enter the viewport, reducing memory and CPU usage.
**Source:** `androidx/compose/foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/lazy/`
## DSL Patterns: item, items, itemsIndexed
### `item` — Single Composable
```kotlin
LazyColumn {
item {
HeaderComposable()
}
}
```
### `items` — From a List or Count
```kotlin
// From a List
val users = listOf(User("Alice"), User("Bob"))
LazyColumn {
items(users) { user ->
UserCard(user)
}
}
// From a count
LazyColumn {
items(100) { index ->
Text("Item $index")
}
}
```
Executable smoke check for the count overload:
```kotlin verify
// name: lazy-column-count-renders-visible-items
// repeat: 3
// assert: text = "Item 0"
// assert-not: text = "Item 3"
@Composable
fun Subject() {
LazyColumn {
items(3) { index ->
Text("Item $index")
}
}
}
```
### `itemsIndexed` — With Index
```kotlin
LazyColumn {
itemsIndexed(users) { index, user ->
Text("${index + 1}. ${user.name}")
}
}
```
## Keys: Critical for Correctness and Performance
The `key` parameter ensures Compose can correctly identify and reuse items even if the list is reordered.
### ✓ Good: Stable Keys
```kotlin
data class User(val id: Long, val name: String)
LazyColumn {
items(users, key = { it.id }) { user ->
UserCard(user)
}
}
```
When `users` list is reordered, Compose knows which item moved because the key (id) is stable.
### ✗ Bad: Index as Key
```kotlin
// AVOID: If list is reordered, state gets mixed up
LazyColumn {
items(users, key = { index }) { user -> // Wrong!
var selected by remember { mutableStateOf(false) }
UserCard(user, selected)
}
}
```
If you remove item at index 0, the item that was at index 1 moves to index 0 and incorrectly inherits the state.
### ✗ Bad: No Key
```kotlin
// If list changes, item state/animations may misbehave
LazyColumn {
items(users) { user ->
UserCard(user)
}
}
```
Without a key, Compose can't distinguish items reliably if the list changes.
**Rule:** Always provide a stable, unique key when the list can change. Use IDs, not indices.
## Content Types for Recycling Optimization
Use `contentType` to enable layout reuse when rendering different item types:
```kotlin
sealed class ListItem
data class HeaderItem(val title: String) : ListItem()
data class UserItem(val user: User) : ListItem()
LazyColumn {
items(
items = listItems,
key = { it.id },
contentType = { when (it) {
is HeaderItem -> "header"
is UserItem -> "user"
}}
) { item ->
when (item) {
is HeaderItem -> HeaderComposable(item)
is UserItem -> UserCard(item)
}
}
}
```
Items with the same `contentType` can reuse layout state, improving performance when types repeat.
## LazyListState: Scroll Position and Animations
Manage scroll position programmatically:
```kotlin
val listState = rememberLazyListState()
LazyColumn(state = listState) {
items(100) { index ->
Text("Item $index")
}
}
// Scroll to item 50
LaunchedEffect(Unit) {
listState.scrollToItem(50)
}
// Animate scroll
LaunchedEffect(Unit) {
listState.animateScrollToItem(50)
}
// Read current scroll position
val firstVisibleIndex = listState.firstVisibleItemIndex
val firstVisibleOffset = listState.firstVisibleItemScrollOffset
```
**Use case:** Scroll to a newly added item, or scroll on user action.
## LazyVerticalGrid and LazyHorizontalGrid
### Fixed Columns
```kotlin
LazyVerticalGrid(columns = GridCells.Fixed(3)) {
items(itemList.size) { index ->
GridItemComposable(itemList[index])
}
}
```
### Adaptive Columns (Responsive)
```kotlin
// Column width ~100dp, fills available space with as many columns as fit
LazyVerticalGrid(columns = GridCells.Adaptive(100.dp)) {
items(itemList.size) { index ->
GridItemComposable(itemList[index])
}
}
```
Adaptive is preferable for responsive layouts.
## LazyVerticalStaggeredGrid
For Pinterest-style layouts with variable heights:
```kotlin
LazyVerticalStaggeredGrid(
columns = StaggeredGridCells.Fixed(2),
modifier = Modifier.fillMaxSize()
) {
items(images.size) { index ->
AsyncImage(
model = images[index].url,
contentDescription = null,
modifier = Modifier.fillMaxWidth()
)
}
}
```
Items flow into the column with the shortest current height, creating a natural staggered appearance.
## HorizontalPager and VerticalPager
Page-by-page horizontal or vertical swiping:
```kotlin
val pagerState = rememberPagerState(pageCount = { pages.size })
HorizontalPager(state = pagerState) { page ->
PageComposable(pages[page])
}
// Programmatic scroll to page
LaunchedEffect(Unit) {
pagerState.scrollToPage(2)
}
// Animate to page
LaunchedEffect(Unit) {
pagerState.animateScrollToPage(2)
}
```
## Sticky Headers in Lazy Lists
Headers that remain visible at the top while scrolling:
```kotlin
LazyColumn {
stickyHeader {
SectionHeaderComposable("Section A")
}
items(itemsA) { item ->
ItemComposable(item)
}
stickyHeader {
SectionHeaderComposable("Section B")
}
items(itemsB) { item ->
ItemComposable(item)
}
}
```
## Nested Scrolling: Pitfalls
### ✗ Avoid Scrollable Inside LazyColumn
```kotlin
// Bad: nested scroll behavior is unpredictable
LazyColumn {
item {
LazyRow { // Nested lazy is OK, but...
items(innerList) { item ->
InnerItem(item)
}
}
}
}
```
Nested lazy composables are acceptable but require careful thought about scroll precedence.
### ✗ Avoid verticalScroll Modifier Inside LazyColumn
```kotlin
// Bad: two scroll containers fight for input
LazyColumn {
item {
Column(modifier = Modifier.verticalScroll(rememberScrollState())) {
Text("This is scrollable twice!")
}
}
}
```
Don't wrap lazy children in scrollable modifiers; use nested lazy composables if you need multiple scroll axes.
### ✓ Use nestedScroll for Complex Scenarios
```kotlin
val scrollState = rememberScrollState()
val nestedScrollConnection = remember {
object : NestedScrollConnection {
override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
// Custom scroll handling
return Offset.Zero
}
}
}
LazyColumn(modifier = Modifier.nestedScroll(nestedScrollConnection)) {
items(100) { index ->
Text("Item $index")
}
}
```
## Performance: Scroll-Dependent UI
### ✗ Bad: Heavy Computation in Item Lambda
```kotlin
LazyColumn {
items(users) { user ->
val processedData = expensiveComputation(user) // Runs every recomposition!
UserCard(user, processedData)
}
}
```
### ✓ Good: Use derivedStateOf for Scroll-Dependent Logic
```kotlin
val listState = rememberLazyListState()
val showScrollToTop = remember {
derivedStateOf { listState.firstVisibleItemIndex > 0 }
}
LazyColumn(state = listState) {
items(100) { index ->
Text("Item $index")
}
}
if (showScrollToTop.value) {
Button(onClick = { /* scroll up */ }) { Text("Top") }
}
```
`derivedStateOf` derives a new value when scroll state changes without recomposing the entire list.
## Keys in Non-Lazy Layouts
`key {}` is not only for lazy lists. A `Column`, `Row`, or `Box` that emits children with
`forEach` identifies them by **position**, so per-child `remember` state (gesture offsets,
animations, text input) follows the slot, not the item, when the list is reordered, inserted
into, or filtered.
```kotlin
items.forEach { item ->
key(item.id) {
DraggableCard(item) // remembered state now follows item.id
}
}
```
Use a stable, unique key (database id, UUID), never the index. Lazy-list `key`/`contentType`
rules above are separate: non-lazy layouts have no `contentType` or recycling.
## Anti-Patterns
### ✗ Using LazyColumn for Small Fixed Lists
```kotlin
// Bad: overkill for 5 items
LazyColumn {
items(5) { index ->
Text("Item $index")
}
}
```
**Better:** Use `Column` for small fixed lists.
### ✗ No Keys + List Mutations
```kotlin
var items by remember { mutableStateOf(initialList) }
LazyColumn {
items(items) { item -> // No key!
ItemComposable(item, onDelete = {
items = items.filter { it.id != item.id }
})
}
}
```
Without keys, removing an item corrupts the state of remaining items.
### ✗ Creating New Objects in Keys
```kotlin
// Bad: key creates new object each recomposition
LazyColumn {
items(users, key = { User(it.id, it.name) }) { user ->
UserCard(user)
}
}
```
**Better:** Use primitive stable identifiers.
## Key Takeaways
1. Always provide stable, unique keys when using `items` on mutable lists
2. Use `contentType` for multi-type lists to enable layout reuse
3. Prefer `GridCells.Adaptive` for responsive grid layouts
4. Avoid nested scrollables; use `nestedScroll` for complex scroll behavior
5. Use `derivedStateOf` to avoid recomposing the entire list for scroll-dependent logic
6. `LazyColumn`/`LazyRow` are for large or unbounded lists; use `Column`/`Row` for small fixed lists
7. Never use indices as keys; list mutations will corrupt item state
### Production Crash Patterns
#### indexOf() Inside items {} — O(n^2) and Crashes
```kotlin
// BAD: O(n^2) total, returns -1 on recreated objects → IndexOutOfBoundsException
items(list.size) { index ->
val item = list[index]
val position = list.indexOf(item) // -1 if object was recreated!
}
// GOOD: use items() with key for stable identity
items(list, key = { it.id }) { item ->
ItemRow(item)
}
```
Root cause: `indexOf()` uses `equals()`. If list items are recreated (new object instances without proper `equals()` implementation), `indexOf()` returns -1.
#### Duplicate LazyColumn Keys
Backend sends items without unique IDs, or WebSocket reconnects deliver duplicates → `IllegalArgumentException: Key X was already used`.
```kotlin
// BAD: backend IDs may not be unique
items(messages, key = { it.id }) { msg -> ... }
// GOOD: add dedup index for safety
items(messages, key = { "${it.id}_${it.dedupIndex}" }) { msg -> ... }
```
The `dedupIndex` pattern: Add a field to the data class that is excluded from `equals()`/`hashCode()` but included in the LazyColumn key:
```kotlin
data class ChatMessage(
val id: String,
val text: String,
val timestamp: Long
) {
// NOT in data class constructor — excluded from equals/hashCode
var dedupIndex: Int = 0
}
// When processing messages from backend:
fun deduplicateKeys(messages: List<ChatMessage>): List<ChatMessage> {
val seen = mutableMapOf<String, Int>()
return messages.map { msg ->
val count = seen.getOrPut(msg.id) { 0 }
seen[msg.id] = count + 1
msg.also { it.dedupIndex = count }
}
}
```
#### derivedStateOf Driving Collection Size → IOOB
```kotlin
// BAD: derived count can be stale when items{} reads
val itemCount by remember { derivedStateOf { filterItems(allItems).size } }
LazyColumn {
items(itemCount) { index ->
val item = filterItems(allItems)[index] // IOOB if allItems changed!
}
}
// GOOD: derive the full filtered list, not just the count
val filteredItems by remember { derivedStateOf { filterItems(allItems) } }
LazyColumn {
items(filteredItems, key = { it.id }) { item ->
ItemRow(item)
}
}
```
Rule: `derivedStateOf` for scroll direction, visibility, form validation — **never for item counts that drive LazyList rendering**.
### LazyList Hardening
#### Multi-Field Keys with Collision Prefixes
When a LazyList mixes items from different data sources, IDs can collide:
```kotlin
// BAD: id=42 in both liveItems and archivedItems → crash
LazyColumn {
items(liveItems, key = { it.id }) { ... }
items(archivedItems, key = { it.id }) { ... }
}
// GOOD: prefix keys by source
LazyColumn {
items(liveItems, key = { "live_${it.id}" }) { ... }
items(archivedItems, key = { "archived_${it.id}" }) { ... }
items(pinnedItems, key = { "pinned_${it.id}" }) { ... }
}
```
#### items() with key Preferred Over itemsIndexed()
`items(list, key = { it.id })` gives each item a stable identity across recompositions. This enables:
- Correct `animateItem()` animations
- Efficient diffing (only changed items recompose)
- Proper state preservation per item
Use `itemsIndexed()` only when you genuinely need the index for display (e.g., numbered list).
#### animateItem() Parameters
```kotlin
items(items, key = { it.id }) { item ->
ItemRow(
item = item,
modifier = Modifier.animateItem(
fadeInSpec = tween(durationMillis = 250),
placementSpec = spring(
dampingRatio = Spring.DampingRatioLowBouncy,
stiffness = Spring.StiffnessMediumLow
),
fadeOutSpec = tween(durationMillis = 150)
)
)
}
```
#### ReportDrawnWhen for Startup Performance
Signal to the system that the first meaningful content is visible:
```kotlin
@Composable
fun ConversationListScreen(items: List<Conversation>) {
ReportDrawnWhen { items.isNotEmpty() }
LazyColumn {
items(items, key = { it.id }) { item ->
ConversationRow(item)
}
}
}
```
This improves Time To Initial Display (TTID) and Time To Full Display (TTFD) metrics in Android vitals.
#### Device-Specific Pagination
Some devices (notably Samsung) handle scroll events differently, requiring fewer scroll confirmations for lazy load triggers. When implementing infinite scroll, test on multiple OEMs and consider a configurable scroll threshold.
```kotlin
val shouldLoadMore by remember {
derivedStateOf {
val lastVisibleItem = listState.layoutInfo.visibleItemsInfo.lastOrNull()?.index ?: 0
val totalItems = listState.layoutInfo.totalItemsCount
lastVisibleItem >= totalItems - PREFETCH_THRESHOLD // e.g., 5
}
}
LaunchedEffect(shouldLoadMore) {
if (shouldLoadMore) { viewModel.loadNextPage() }
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |