Skip to main content

List

Rows grouped into a section, as in a settings screen. Each row has a title and optional description, something before it (an icon or avatar), and a value, control or chevron after it. iOS draws an inset grouped table with separators that start at the text; Material draws full-width rows without dividers; the web draws an outlined box.

Import
import { List, ListItem } from 'patine-ui';
Subpath
patine-ui/list
Source
GitHubMarkdown for LLMs
Runs on
iOSAndroidWebFree · MIT
Loading…
<VStack gap="xl">
  <List>
    <ListItem title="Ava Martin" description="[email protected]" leading={<Avatar name="Ava Martin" />} onPress={() => {}} />
  </List>
  <List title="General" footer="We only send what you turn on.">
    <ListItem title="Notifications" trailing={<Switch accessibilityLabel="Notifications" defaultChecked />} />
    <ListItem title="Language" value="English" onPress={() => {}} />
    <ListItem title="Sign out" destructive showChevron={false} onPress={() => {}} />
  </List>
</VStack>

Try the props​

Props
title
footer
design
<List
title="General"
footer="Changes apply on every device."
>
…
</List>

Examples​

Each example is live: edit the code and it runs.

A settings screen​

Several Lists, each a section with its own title and footer, make a settings screen. Rows carry an icon in leading, and a value, a Badge or a Switch at the end.

Loading…
<VStack gap="xl" style={{ maxWidth: 420, width: '100%' }}>
  <List>
    <ListItem
      title="Maya Cohen"
      description="Apple Account, iCloud and more"
      leading={<Avatar name="Maya Cohen" src="https://picsum.photos/id/64/160/160" />}
      onPress={() => {}}
    />
  </List>
  <List title="Connectivity">
    <ListItem title="Airplane mode" leading={<Tile name="plane" color="#F97316" />} trailing={<Switch accessibilityLabel="Airplane mode" checked={airplane} onCheckedChange={setAirplane} />} />
    <ListItem title="Wi-Fi" leading={<Tile name="wifi" color="#3B82F6" />} value={airplane ? 'Off' : 'Home 5G'} onPress={() => {}} disabled={airplane} />
    <ListItem title="Bluetooth" leading={<Tile name="bluetooth" color="#3B82F6" />} value="On" onPress={() => {}} />
  </List>
  <List title="General" footer="Updates install overnight while your phone is charging.">
    <ListItem title="Software update" leading={<Tile name="settings" color="#8E8E93" />} trailing={<Badge variant="destructive">1</Badge>} onPress={() => {}} />
    <ListItem title="Storage" description="48.2 GB of 128 GB used" leading={<Tile name="database" color="#8E8E93" />} onPress={() => {}} />
  </List>
</VStack>

Open a conversation​

Give a row onPress and it becomes a button. In the brand and iOS designs it also gets a chevron; set showChevron to force it on or off.

Loading…
<List title="Messages" style={{ maxWidth: 420, width: '100%' }}>
  {THREADS.map((t) => (
    <ListItem
      key={t.name}
      title={t.name}
      description={t.last}
      leading={<Avatar name={t.name} />}
      trailing={<Text size="sm" color="textSecondary">{t.time}</Text>}
      showChevron={false}
      onPress={() => {}}
    />
  ))}
</List>

Picking one row​

For a short list of choices, mark the chosen row with a check in trailing, as iOS Settings does. For a longer list, use SelectList.

Loading…
<List title="App language" footer="The app restarts to apply it." style={{ maxWidth: 420, width: '100%' }}>
  {LANGUAGES.map((name) => (
    <ListItem
      key={name}
      title={name}
      showChevron={false}
      onPress={() => setLanguage(name)}
      accessibilityState={{ selected: name === language }}
      trailing={name === language ? <Icon name="check" color="primary" strokeWidth={2} /> : null}
    />
  ))}
</List>

Account settings with Sign out and Delete​

disabled dims a row and blocks presses. destructive draws the title in the danger color, for rows such as "Delete account"; put them in their own section at the end.

Loading…
<VStack gap="xl" style={{ maxWidth: 420, width: '100%' }}>
  <List title="Account">
    <ListItem title="Email" value="[email protected]" onPress={() => {}} />
    <ListItem title="Two-factor authentication" value="Requires a verified phone" disabled onPress={() => {}} />
  </List>
  <List>
    <ListItem title="Sign out" showChevron={false} onPress={() => {}} />
    <ListItem title="Delete account" destructive showChevron={false} onPress={() => {}} />
  </List>
</VStack>

In real apps​

Patine Pro screens built with it. Each opens on that screen, live, in the screens gallery.

Designs​

iOS draws an inset grouped table with a section title above; Material uses full-width rows with a title in the primary color; Patine and the web use a bordered card.

Display

Dark mode
Patine

Display

Dark mode
iOS

Display

Dark mode
Material

Display

Dark mode
Web

Guidelines​

Do

Show the current value. People see the setting without opening it.

Don’t

Don't make people open a row to see it. A bare chevron hides what's set.

Wi-Fi
Do

Name the control after its row. A switch in trailing gets its own label, usually the row's title.

Don’t

Don't make the row and its switch do different things. Pressing anywhere on the row should do what the switch does.

Accessibility​

Behaviour
RoleA row with onPress is a button named by its title, description and value together. The section title is a heading.
Announceddisabled; set accessibilityState={{ selected }} on a row that marks a choice, as in Picking one row.
Keyboard (web)Pressable rows take Tab focus and press with Enter or Space.
Touch targetEvery row is at least 44pt tall.
Reduce motionRows don't animate.
  • Put a control in trailing with its own accessibilityLabel (usually the row's title), since the row itself isn't the control.

API​

List​

List also takes View props.

PropTypeDefaultDescription
titlestring—A section heading above the rows.
footerstring—A note under the rows.
childrenReactNode—ListItem rows.
styles{ content?: StyleProp<ViewStyle> }—Style slots: content is the box around the rows.
themeDeepPartial<Theme>—Theme override, passed to the rows.
designDesignfrom PatineProviderThe look to follow, passed to the rows.

ListItem​

PropTypeDefaultDescription
titlestringRequiredRequired.
descriptionstring—A second line.
leadingReactNode—An icon or avatar before the text.
trailingReactNode—A control after the text, such as a Switch or Badge.
valuestring—The current value, in secondary text at the end.
showChevronbooleanwith onPress, in brand and iOSA chevron at the end.
destructivebooleanfalseThe title in the danger color.
disabledbooleanfalseDims the row and blocks presses.
onPress(event) => void—Makes the row a button.
hrefstring—Makes it a link: a real <a> on the web, Linking.openURL on iOS and Android after onPress (call event.preventDefault() to stop it).
externalbooleanfalseOpens href in a new tab on the web.
styles{ title?: StyleProp<TextStyle> }—Style slots: title is the title's text.
themeDeepPartial<Theme>from ListTheme override.
designDesignfrom ListThe look to follow.

Right to left and custom styles work the same on every component: see Internationalization and right to left and Styling.

For AI​

Give this page to an assistant as Markdown, with Copy page at the top, or the whole API in llms-full.txt.

With the Patine MCP server, it asks for get_component_docs({ name: "List" })