androidx.tv.foundation.lazy.list

Interfaces

TvLazyListItemInfo

Contains useful information about an individual item in lazy lists like TvLazyColumn or TvLazyRow.

TvLazyListItemScope
TvLazyListLayoutInfo

Contains useful information about the currently displayed layout state of lazy lists like TvLazyColumn or TvLazyRow.

TvLazyListScope

Receiver scope which is used by TvLazyColumn and TvLazyRow.

Classes

TvLazyListState

A state object that can be hoisted to control and observe scrolling.

Annotations

TvLazyListScopeMarker

DSL marker used to distinguish between lazy layout scope and the item scope.

Top-level functions summary

Unit
@Composable
TvLazyColumn(
    modifier: Modifier,
    state: TvLazyListState,
    contentPadding: PaddingValues,
    reverseLayout: Boolean,
    verticalArrangement: Arrangement.Vertical,
    horizontalAlignment: Alignment.Horizontal,
    userScrollEnabled: Boolean,
    pivotOffsets: PivotOffsets,
    content: TvLazyListScope.() -> Unit
)

The vertically scrolling list that only composes and lays out the currently visible items.

Unit
@Composable
TvLazyRow(
    modifier: Modifier,
    state: TvLazyListState,
    contentPadding: PaddingValues,
    reverseLayout: Boolean,
    horizontalArrangement: Arrangement.Horizontal,
    verticalAlignment: Alignment.Vertical,
    userScrollEnabled: Boolean,
    pivotOffsets: PivotOffsets,
    content: TvLazyListScope.() -> Unit
)

The horizontally scrolling list that only composes and lays out the currently visible items.

TvLazyListState
@Composable
rememberTvLazyListState(
    initialFirstVisibleItemIndex: Int,
    initialFirstVisibleItemScrollOffset: Int
)

Creates a TvLazyListState that is remembered across compositions.

Extension functions summary

inline Unit
<T : Any?> TvLazyListScope.items(
    items: Array<T>,
    noinline key: ((item) -> Any)?,
    noinline contentType: (item) -> Any,
    crossinline itemContent: @Composable TvLazyListItemScope.(item) -> Unit
)

Adds an array of items.

inline Unit
<T : Any?> TvLazyListScope.items(
    items: List<T>,
    noinline key: ((item) -> Any)?,
    noinline contentType: (item) -> Any,
    crossinline itemContent: @Composable TvLazyListItemScope.(item) -> Unit
)

Adds a list of items.

inline Unit
<T : Any?> TvLazyListScope.itemsIndexed(
    items: Array<T>,
    noinline key: ((index: Int, item) -> Any)?,
    crossinline contentType: (index: Int, item) -> Any,
    crossinline itemContent: @Composable TvLazyListItemScope.(index: Int, item) -> Unit
)

Adds an array of items where the content of an item is aware of its index.

inline Unit
<T : Any?> TvLazyListScope.itemsIndexed(
    items: List<T>,
    noinline key: ((index: Int, item) -> Any)?,
    crossinline contentType: (index: Int, item) -> Any,
    crossinline itemContent: @Composable TvLazyListItemScope.(index: Int, item) -> Unit
)

Adds a list of items where the content of an item is aware of its index.

Top-level functions

TvLazyColumn

@Composable
fun TvLazyColumn(
    modifier: Modifier = Modifier,
    state: TvLazyListState = rememberTvLazyListState(),
    contentPadding: PaddingValues = PaddingValues(0.dp),
    reverseLayout: Boolean = false,
    verticalArrangement: Arrangement.Vertical = if (!reverseLayout) Arrangement.Top else Arrangement.Bottom,
    horizontalAlignment: Alignment.Horizontal = Alignment.Start,
    userScrollEnabled: Boolean = true,
    pivotOffsets: PivotOffsets = PivotOffsets(),
    content: TvLazyListScope.() -> Unit
): Unit

The vertically scrolling list that only composes and lays out the currently visible items. The content block defines a DSL which allows you to emit items of different types. For example you can use TvLazyListScope.item to add a single item and TvLazyListScope.items to add a list of items.

Parameters
modifier: Modifier = Modifier

the modifier to apply to this layout.

state: TvLazyListState = rememberTvLazyListState()

the state object to be used to control or observe the list's state.

contentPadding: PaddingValues = PaddingValues(0.dp)

a padding around the whole content. This will add padding for the. content after it has been clipped, which is not possible via modifier param. You can use it to add a padding before the first item or after the last one. If you want to add a spacing between each item use verticalArrangement.

reverseLayout: Boolean = false

reverse the direction of scrolling and layout. When true, items are laid out in the reverse order and TvLazyListState.firstVisibleItemIndex == 0 means that column is scrolled to the bottom. Note that reverseLayout does not change the behavior of verticalArrangement, e.g. with Arrangement.Top (top) 123### (bottom) becomes (top) 321### (bottom).

verticalArrangement: Arrangement.Vertical = if (!reverseLayout) Arrangement.Top else Arrangement.Bottom

The vertical arrangement of the layout's children. This allows to add a spacing between items and specify the arrangement of the items when we have not enough of them to fill the whole minimum size.

horizontalAlignment: Alignment.Horizontal = Alignment.Start

the horizontal alignment applied to the items.

userScrollEnabled: Boolean = true

whether the scrolling via the user gestures or accessibility actions is allowed. You can still scroll programmatically using the state even when it is disabled.

pivotOffsets: PivotOffsets = PivotOffsets()

offsets of child element within the parent and starting edge of the child from the pivot defined by the parentOffset. TvLazyListScope.item to add a single item or TvLazyListScope.items to add a list of items.

content: TvLazyListScope.() -> Unit

a block which describes the content. Inside this block you can use methods like

TvLazyRow

@Composable
fun TvLazyRow(
    modifier: Modifier = Modifier,
    state: TvLazyListState = rememberTvLazyListState(),
    contentPadding: PaddingValues = PaddingValues(0.dp),
    reverseLayout: Boolean = false,
    horizontalArrangement: Arrangement.Horizontal = if (!reverseLayout) Arrangement.Start else Arrangement.End,
    verticalAlignment: Alignment.Vertical = Alignment.Top,
    userScrollEnabled: Boolean = true,
    pivotOffsets: PivotOffsets = PivotOffsets(),
    content: TvLazyListScope.() -> Unit
): Unit

The horizontally scrolling list that only composes and lays out the currently visible items. The content block defines a DSL which allows you to emit items of different types. For example you can use TvLazyListScope.item to add a single item and TvLazyListScope.items to add a list of items.

Parameters
modifier: Modifier = Modifier

the modifier to apply to this layout

state: TvLazyListState = rememberTvLazyListState()

the state object to be used to control or observe the list's state

contentPadding: PaddingValues = PaddingValues(0.dp)

a padding around the whole content. This will add padding for the content after it has been clipped, which is not possible via modifier param. You can use it to add a padding before the first item or after the last one. If you want to add a spacing between each item use horizontalArrangement.

reverseLayout: Boolean = false

reverse the direction of scrolling and layout. When true, items are laid out in the reverse order and TvLazyListState.firstVisibleItemIndex == 0 means that row is scrolled to the end. Note that reverseLayout does not change the behavior of horizontalArrangement, e.g. with 123### becomes 321###.

horizontalArrangement: Arrangement.Horizontal = if (!reverseLayout) Arrangement.Start else Arrangement.End

The horizontal arrangement of the layout's children. This allows to add a spacing between items and specify the arrangement of the items when we have not enough of them to fill the whole minimum size.

verticalAlignment: Alignment.Vertical = Alignment.Top

the vertical alignment applied to the items

userScrollEnabled: Boolean = true

whether the scrolling via the user gestures or accessibility actions is allowed. You can still scroll programmatically using the state even when it is disabled.

pivotOffsets: PivotOffsets = PivotOffsets()

offsets of child element within the parent and starting edge of the child from the pivot defined by the parentOffset.

content: TvLazyListScope.() -> Unit

a block which describes the content. Inside this block you can use methods like TvLazyListScope.item to add a single item or TvLazyListScope.items to add a list of items.

rememberTvLazyListState

@Composable
fun rememberTvLazyListState(
    initialFirstVisibleItemIndex: Int = 0,
    initialFirstVisibleItemScrollOffset: Int = 0
): TvLazyListState

Creates a TvLazyListState that is remembered across compositions.

Changes to the provided initial values will not result in the state being recreated or changed in any way if it has already been created.

Parameters
initialFirstVisibleItemIndex: Int = 0

the initial value for TvLazyListState.firstVisibleItemIndex

initialFirstVisibleItemScrollOffset: Int = 0

the initial value for TvLazyListState.firstVisibleItemScrollOffset

Extension functions

inline fun <T : Any?> TvLazyListScope.items(
    items: Array<T>,
    noinline key: ((item) -> Any)? = null,
    noinline contentType: (item) -> Any = { null },
    crossinline itemContent: @Composable TvLazyListItemScope.(item) -> Unit
): Unit

Adds an array of items.

Parameters
items: Array<T>

the data array

noinline key: ((item) -> Any)? = null

a factory of stable and unique keys representing the item. Using the same key for multiple items in the list is not allowed. Type of the key should be saveable via Bundle on Android. If null is passed the position in the list will represent the key. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one.

noinline contentType: (item) -> Any = { null }

a factory of the content types for the item. The item compositions of the same type could be reused more efficiently. Note that null is a valid type and items of such type will be considered compatible.

crossinline itemContent: @Composable TvLazyListItemScope.(item) -> Unit

the content displayed by a single item

inline fun <T : Any?> TvLazyListScope.items(
    items: List<T>,
    noinline key: ((item) -> Any)? = null,
    noinline contentType: (item) -> Any = { null },
    crossinline itemContent: @Composable TvLazyListItemScope.(item) -> Unit
): Unit

Adds a list of items.

Parameters
items: List<T>

the data list

noinline key: ((item) -> Any)? = null

a factory of stable and unique keys representing the item. Using the same key for multiple items in the list is not allowed. Type of the key should be saveable via Bundle on Android. If null is passed the position in the list will represent the key. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one.

noinline contentType: (item) -> Any = { null }

a factory of the content types for the item. The item compositions of the same type could be reused more efficiently. Note that null is a valid type and items of such type will be considered compatible.

crossinline itemContent: @Composable TvLazyListItemScope.(item) -> Unit

the content displayed by a single item

itemsIndexed

inline fun <T : Any?> TvLazyListScope.itemsIndexed(
    items: Array<T>,
    noinline key: ((index: Int, item) -> Any)? = null,
    crossinline contentType: (index: Int, item) -> Any = { _, _ -> null },
    crossinline itemContent: @Composable TvLazyListItemScope.(index: Int, item) -> Unit
): Unit

Adds an array of items where the content of an item is aware of its index.

Parameters
items: Array<T>

the data array

noinline key: ((index: Int, item) -> Any)? = null

a factory of stable and unique keys representing the item. Using the same key for multiple items in the list is not allowed. Type of the key should be saveable via Bundle on Android. If null is passed the position in the list will represent the key. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one.

crossinline contentType: (index: Int, item) -> Any = { _, _ -> null }

a factory of the content types for the item. The item compositions of the same type could be reused more efficiently. Note that null is a valid type and items of such type will be considered compatible.

crossinline itemContent: @Composable TvLazyListItemScope.(index: Int, item) -> Unit

the content displayed by a single item

itemsIndexed

inline fun <T : Any?> TvLazyListScope.itemsIndexed(
    items: List<T>,
    noinline key: ((index: Int, item) -> Any)? = null,
    crossinline contentType: (index: Int, item) -> Any = { _, _ -> null },
    crossinline itemContent: @Composable TvLazyListItemScope.(index: Int, item) -> Unit
): Unit

Adds a list of items where the content of an item is aware of its index.

Parameters
items: List<T>

the data list

noinline key: ((index: Int, item) -> Any)? = null

a factory of stable and unique keys representing the item. Using the same key for multiple items in the list is not allowed. Type of the key should be saveable via Bundle on Android. If null is passed the position in the list will represent the key. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one.

crossinline contentType: (index: Int, item) -> Any = { _, _ -> null }

a factory of the content types for the item. The item compositions of the same type could be reused more efficiently. Note that null is a valid type and items of such type will be considered compatible.

crossinline itemContent: @Composable TvLazyListItemScope.(index: Int, item) -> Unit

the content displayed by a single item