This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 58).
List
A virtualized vertical container of rows, paired with a tappable ListItem primitive.
List provides a virtualized vertical container of rows, typically populated with ListItem children. It provides the platform-native chrome (separators, inset styling, pull-to-refresh). ListItem is a tappable row with leading/trailing/supportingText slots.
For large data sets, render rows with
List.ForEach. It mounts only the rows near the visible range, and reuses them while the list scrolls.
Native implementations


Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
Usage
Basic list
Rows with slots
ListItem accepts leading, trailing, and supportingText shorthand props for the common case. Pass a ReactNode for any of them when richer content is needed.
Compound slot children
For full control over slot content, use the compound API: <ListItem.Leading>, <ListItem.Trailing>, and <ListItem.Supporting>. Anything not wrapped in a slot becomes the headline.
Large data sets
List.ForEach renders one row for each item of data. It mounts a small pool of rows around the visible range and reuses them while the list scrolls. Rows that are not ready yet show a placeholder of estimatedItemSize.
Wrap the render function in useCallback. A recycled row keeps its local state (useState) when it shows another item. Keep row state outside the row, or reset it when the item changes. You can put static rows before and after List.ForEach in the same List.
Pull-to-refresh
Pass an async onRefresh handler. The platform-native refresh indicator stays visible until the returned promise settles (resolves or rejects).
Pull-to-refresh is not implemented on web yet. The handler is accepted for API parity but the indicator only appears on Android and iOS.
API
import { List, ListItem } from '@expo/ui';
Components
Type: React.Element<ListProps>
A vertical container of rows.
Typically populated with ListItem children.
() => Promise<void>Optional pull-to-refresh handler. When provided, the list shows the platform-native refresh affordance. The returned promise drives the indicator's visibility.
Type: React.Element<ListForEachProps<T>>
Renders one row for each item of data, and reuses rows while the list scrolls.
(info: {
index: number,
item: T
}) => ReactElementRenders a row. Wrap it in useCallback, or every row re-renders on each parent render.
A recycled row keeps its local state (useState) when it shows another item.
number • Default: 64Row height to use until a row is measured: dp on Android, points on iOS (without the row insets), and pixels on web.
(item: T, index: number) => stringReturns a stable, unique string key for each item.
number • Default: 10Extra rows to render above and below the visible rows.
Components
Type: React.Element<ListItemProps>
A tappable row in a list.
Composes with List.
Pass row content via the leading / trailing / supportingText shorthand props or the compound <ListItem.Leading> / <ListItem.Trailing> / <ListItem.Supporting> slot children.
Props for the ListItem component.
A tappable row in a list.
ReactNodeHeadline content of the row. The remaining (non-slot) children are rendered in the headline area.
ListItemColorsRow colors. Applied on Android via Compose's ListItem.colors.
ReactNodeShorthand for the leading slot.
Overridden by <ListItem.Leading> if both are provided.
ModifierConfig[]Platform-specific modifier escape hatch. Pass an array of modifier configs
from @expo/ui/swift-ui/modifiers or @expo/ui/jetpack-compose/modifiers.
On iOS these are applied to the underlying SwiftUI Button and can override
its default buttonStyle(.plain).
() => voidTap handler. Activates over the entire row rectangle, including the empty gap between leading/headline/trailing.
ReactNodeShorthand for the supporting (sub-)text slot.
Strings are rendered with platform-appropriate secondary styling; pass a ReactNode for richer content.
Overridden by <ListItem.Supporting> if both are provided.
stringIdentifier used to locate the component in end-to-end tests.
ReactNodeShorthand for the trailing slot.
Overridden by <ListItem.Trailing> if both are provided.