LazyRow

A Jetpack Compose LazyRow component for displaying horizontally scrolling lists.

Android

Included in Expo Go

GitHub

npm

Changelog

Recommended version:

~58.0.10

Expo UI LazyRow matches the official Jetpack Compose LazyRow API and displays a horizontally scrolling list.

LazyRow rendering colored category cards in a horizontally scrolling list

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 row

Each child of LazyRow is one item. Use the horizontalArrangement prop to space the items and the contentPadding prop to add padding around the list content.

BasicLazyRow.tsx

import {
  Host,
  LazyRow,
  Text,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import {
  border,
  padding,
} from '@expo/ui/jetpack-compose/modifiers';

export default function BasicLazyRow() {
  const colors = useMaterialColors();

  return (
    <Host style={{ height: 100 }}>
      <LazyRow
        horizontalArrangement={{ spacedBy: 8 }}
        verticalAlignment="center">
        <Text
          style={{ fontSize: 28 }}
          color={colors.onBackground}
          modifiers={[
            border(1, colors.outline),
            padding(12, 6, 12, 6),
          ]}>
          Photos
        </Text>
        <Text
          style={{ fontSize: 28 }}
          color={colors.onBackground}
          modifiers={[
            border(1, colors.outline),
            padding(12, 6, 12, 6),
          ]}>
          Music
        </Text>
        <Text
          style={{ fontSize: 28 }}
          color={colors.onBackground}
          modifiers={[
            border(1, colors.outline),
            padding(12, 6, 12, 6),
          ]}>
          Videos
        </Text>
      </LazyRow>
    </Host>
  );
}

Large lists

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

LargeLazyRow.tsx

import {
  Host,
  LazyRow,
  Text,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import {
  border,
  padding,
} from '@expo/ui/jetpack-compose/modifiers';

const items = Array.from(
  { length: 10000 },
  (_, i) => `Item ${i + 1}`
);

function Chip({ label }: { label: string }) {
  const colors = useMaterialColors();

  return (
    <Text
      style={{ fontSize: 28 }}
      color={colors.onBackground}
      modifiers={[
        border(1, colors.outline),
        padding(12, 6, 12, 6),
      ]}>
      {label}
    </Text>
  );
}

function renderItem({ item }: { item: string }) {
  return <Chip label={item} />;
}

export default function LargeLazyRow() {
  return (
    <Host style={{ height: 100 }}>
      <LazyRow
        horizontalArrangement={{ spacedBy: 8 }}
        verticalAlignment="center">
        <LazyRow.Items
          data={items}
          keyExtractor={item => item}
          estimatedItemSize={120}>
          {renderItem}
        </LazyRow.Items>
      </LazyRow>
    </Host>
  );
}

Follow these rules when you render items:

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

API

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

Components

`LazyItems`

Android

Type: React.Element<LazyItemsProps<T>>

A block of recycled rows inside LazyColumn or LazyRow, mirroring the Compose items(count, key) builder. Only a small pool of rows around the visible range is mounted, so large data sets stay cheap. Rows that are not ready yet show a placeholder of estimatedItemSize, or of the size last measured for that item.

Mount it as a direct child of LazyColumn or LazyRow.

LazyItemsProps

`children`

Android

Type:

(info: {
  index: number, 
  item: T
}) => ReactElement

Renders an item. Wrap it in useCallback, or every item re-renders on each parent render. Recycled views are reused for other items, so their local state (useState) carries over. Reset it when the item changes, or keep the state outside the view.

`data`

Android

Type: readonly T[]

Items to display. Replace the array when updating data.

`estimatedItemSize`

Android

Optional • Type: number • Default: 64

Placeholder size in dp along the scroll axis, until an item is measured. Must be positive. Ignored when recycling is false.

`keyExtractor`

Android

Type: (item: T, index: number) => string

Returns a stable, unique string key, also used as the lazy list item key.

`overscanCount`

Android

Optional • Type: number • Default: 10

Extra items to prepare on each side of the visible items. Must be a non-negative integer. Ignored when recycling is false.

`recycling`

Android

Optional • Type: boolean • Default: true

Renders only the items near the visible range and reuses them while scrolling. Set to false to render every item at once. Set it once; changing it remounts the items.

`LazyRow`

Android

Type: React.Element<LazyRowProps>

A lazy row component that efficiently displays a horizontally scrolling list.

LazyRowProps

`children`

Android

Optional • Type: ReactNode

The content to display inside the lazy row.

`contentPadding`

Android

Optional • Type: ContentPadding

Content padding in dp.

`horizontalArrangement`

Android

Optional • Literal type: union

The horizontal arrangement of items. Can be a preset string or an object with spacedBy to specify spacing in dp.

Acceptable values are: 'center' | 'start' | 'end' | 'spaceBetween' | 'spaceAround' | 'spaceEvenly' | { spacedBy: number }

`modifiers`

Android

Optional • Type: ModifierConfig[]

Modifiers for the component.

`verticalAlignment`

Android

Optional • Literal type: string

The vertical alignment of items.

Acceptable values are: 'center' | 'top' | 'bottom'