This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

LazyColumn

A Jetpack Compose LazyColumn component for displaying scrollable lists.

Android

Included in Expo Go

Expo UI LazyColumn matches the official Jetpack Compose LazyColumn API and displays a vertically scrolling list.

LazyColumn rendering a settings list of five Material 3 list items

Installation

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

Usage

Basic lazy column

Each child of LazyColumn is one row. Use the verticalArrangement prop to space the rows and the contentPadding prop to add padding around the list content.

BasicLazyColumn.tsx

import {
  Host,
  LazyColumn,
  ListItem,
  Text,
} from '@expo/ui/jetpack-compose';

export default function BasicLazyColumn() {
  return (
    <Host style={{ height: 400 }}>
      <LazyColumn verticalArrangement={{ spacedBy: 8 }}>
        <ListItem>
          <ListItem.HeadlineContent>
            <Text>Wi-Fi</Text>
          </ListItem.HeadlineContent>
          <ListItem.SupportingContent>
            <Text>Connected to Home</Text>
          </ListItem.SupportingContent>
        </ListItem>
        <ListItem>
          <ListItem.HeadlineContent>
            <Text>Bluetooth</Text>
          </ListItem.HeadlineContent>
          <ListItem.SupportingContent>
            <Text>On</Text>
          </ListItem.SupportingContent>
        </ListItem>
        <ListItem>
          <ListItem.HeadlineContent>
            <Text>Notifications</Text>
          </ListItem.HeadlineContent>
          <ListItem.SupportingContent>
            <Text>Allowed for all apps</Text>
          </ListItem.SupportingContent>
        </ListItem>
      </LazyColumn>
    </Host>
  );
}

Large lists

Use LazyColumn.Items to render rows from an array. Pass the items as data, a unique key for each item with keyExtractor, and a children function that returns the row for an item. LazyColumn.Items renders only the rows near the visible area and reuses them while you scroll.

LargeLazyColumn.tsx

import {
  Host,
  LazyColumn,
  ListItem,
  Text,
} from '@expo/ui/jetpack-compose';

type Contact = { id: string; name: string };

const contacts: Contact[] = Array.from(
  { length: 10000 },
  (_, i) => ({
    id: String(i),
    name: `Contact ${i + 1}`,
  })
);

function renderContact({ item }: { item: Contact }) {
  return (
    <ListItem>
      <ListItem.HeadlineContent>
        <Text>{item.name}</Text>
      </ListItem.HeadlineContent>
    </ListItem>
  );
}

export default function LargeLazyColumn() {
  return (
    <Host style={{ height: 400 }}>
      <LazyColumn>
        <LazyColumn.Items
          data={contacts}
          keyExtractor={contact => contact.id}>
          {renderContact}
        </LazyColumn.Items>
      </LazyColumn>
    </Host>
  );
}

Follow these rules when you render rows:

Define the children function outside the component, or wrap it in useCallback. Otherwise, the rows near the visible area render again each time the component renders.
A reused row keeps the local state (useState) of the item it showed before. Reset the state when the item changes, or keep the state outside the row.
A row that is not ready yet shows an empty placeholder. Set estimatedItemSize close to the height of your rows, in density-independent pixels (dp).
Use overscanCount to prepare more rows above and below the visible rows.
To update the rows, pass a new data array. Do not change the array in place.
Set recycling={false} to render every row up front.

API

import { LazyColumn } from '@expo/ui/jetpack-compose';

No API data file found, sorry!