ListItem

A component for displaying rows of items

StarTwinkles

Moon

Sun

Cloud

StarSubtitle

MoonSubtitle

Features

Accepts size prop that works on all styles.

Place an icon before or after.

Works with themes, animations, Group.

Supports variant prop (e.g., outlined).

Use Apply to pass color/size/variant to children.

Installation

ListItem is already installed in tamagui, or you can install it independently:

yarn
npm
bun
pnpm
yarn add @tamagui/list-item

Usage

Basic usage involves providing children or using the title and subTitle props.

import { ListItem, Separator, YGroup } from 'tamagui'
import { ChevronRight } from '@tamagui/lucide-icons' // Example icon

export default () => (
  <YGroup
    self="center"
    borderWidth={1}
    borderColor="$borderColor"
    rounded="$4"
    width={240}
    size="$4"
  >
    <YGroup.Item>
      <ListItem title="Star" icon={ChevronRight} />
    </YGroup.Item>
    <YGroup.Item>
      <ListItem title="Moon" subTitle="Subtitle for Moon" iconAfter={ChevronRight} />
    </YGroup.Item>
    <YGroup.Item>
      <ListItem>Custom children content</ListItem>
    </YGroup.Item>
  </YGroup>
)

Sizing

The size prop adjusts various properties of the ListItem, including padding, minimum height, and the default size for text elements within it. It accepts theme size tokens (e.g., "$3", "$4").

import { ListItem } from 'tamagui'

export default () => <ListItem size="$5" title="Large List Item" />

Title and SubTitle

Use the title and subTitle props for a structured layout. These props accept ReactNode, so you can pass strings or more complex JSX.

If title or subTitle is provided, children will be rendered inside the main text area (under title/subtitle).
ListItem.Title and ListItem.Subtitle components are used internally and can be targeted for styling (see Customization).

import { ListItem, Avatar } from 'tamagui'
import { User } from '@tamagui/lucide-icons'

export default () => (
  <ListItem
    icon={
      <Avatar circular size="$3">
        <Avatar.Image src="/placeholder.png" />
        <Avatar.Fallback bc="$backgroundFocus" />
      </Avatar>
    }
    title="User Profile"
    subTitle="View and edit your profile details."
    iconAfter={User}
    size="$4"
  />
)

Icon Theming

Icons can be passed to icon (before content) or iconAfter (after content) props.

Automatic Sizing & Spacing: Icons are automatically sized based on the ListItem’s size prop. You can override this with the iconSize prop (accepts SizeTokens). Spacing between the icon and text is also automatically applied (40% of the icon’s final size).
Scaling: Use scaleIcon (number, default: 1) to further adjust the icon size relative to its base size.
Component Props: If you pass a component as an icon, it will receive size (the calculated pixel size) as a prop.

import { ListItem } from 'tamagui'
import { Star, Settings } from '@tamagui/lucide-icons'

export default () => (
  <>
    <ListItem icon={Star} title="Default Icon Size" size="$4" />
    <ListItem
      icon={Settings}
      iconSize="$2"
      title="Explicit Icon Size"
      subTitle="iconSize='$2'"
      size="$5"
    />
    <ListItem
      icon={Star}
      scaleIcon={1.5}
      title="Scaled Icon"
      subTitle="scaleIcon={1.5}"
      size="$4"
    />
  </>
)

Variant

ListItem supports a variant prop for different visual styles:

import { ListItem } from 'tamagui'

export default () => <ListItem variant="outlined" title="Outlined Style" />

Currently supports outlined (transparent background with border).

Apply (Context)

Use ListItem.Apply to pass color, size, and variant to multiple children via context:

import { ListItem, YGroup } from 'tamagui'
import { Trash } from '@tamagui/lucide-icons'

export default () => (
  <YGroup>
    <ListItem.Apply color="$red10">
      <YGroup.Item>
        <ListItem icon={Trash} title="Delete item" />
      </YGroup.Item>
      <YGroup.Item>
        <ListItem icon={Trash} title="Remove all" />
      </YGroup.Item>
    </ListItem.Apply>
  </YGroup>
)

The color prop passed to Apply will be inherited by icons within children.

Customization

For customization, Tamagui exports the building blocks: ListItem.Frame, ListItem.Text, ListItem.Title, ListItem.Subtitle, and ListItem.Icon.

import { YStack, ListItem as TamaguiListItem } from 'tamagui'
import { GetProps, styled } from '@tamagui/web'

const CustomFrame = styled(TamaguiListItem.Frame, {
  padding: '$5',
  backgroundColor: '$backgroundHover',
})

const CustomTitle = styled(TamaguiListItem.Title, {
  color: '$red10',
  fontWeight: 'bold',
})

const CustomSubtitle = styled(TamaguiListItem.Subtitle, {
  color: '$gray10',
  fontStyle: 'italic',
})

// Recompose, for example, if you need a different internal structure
export const MyAdvancedListItem = ({
  icon,
  title,
  subTitle,
  children,
  ...frameProps
}) => {
  return (
    <CustomFrame {...frameProps}>
      {icon && <TamaguiListItem.Icon>{icon}</TamaguiListItem.Icon>}
      <YStack flex={1} justify="center">
        {title && <CustomTitle>{title}</CustomTitle>}
        {subTitle && <CustomSubtitle>{subTitle}</CustomSubtitle>}
        {children && <TamaguiListItem.Text>{children}</TamaguiListItem.Text>}
      </YStack>
      {/* iconAfter could go here */}
    </CustomFrame>
  )
}

API Reference

ListItem

ListItems extend Stack views, inheriting all the Tamagui standard props, plus:

Props

title

React.ReactNode

Main text content of the list item. Renders using `ListItem.Title`.

subTitle

React.ReactNode

Secondary text content, rendered below the title. Renders using `ListItem.Subtitle`.

size

SizeTokens

Adjusts padding, min-height, and default font/icon sizes. Uses theme size tokens (e.g., "$3", "$4").

variant

'outlined'

Visual variant style. Currently supports "outlined" (transparent background with border).

icon

JSX.Element | React.ComponentType<{ size?: number }>

Icon element or component displayed before the main content. Receives `size` prop if a component.

iconAfter

JSX.Element | React.ComponentType<{ size?: number }>

Icon element or component displayed after the main content. Receives `size` prop if a component.

iconSize

SizeTokens

Explicitly set the size of the icon, overriding the default size derived from the ListItem's `size` prop. Uses theme size tokens (e.g., "$2").

scaleIcon

number

Scale factor for the icon (default: 1). Applied after `iconSize` or default size calculation.

disabled

boolean

If true, reduces opacity and disables pointer events.

unstyled

boolean

Removes all default Tamagui styles (padding, background, etc.). Default is `false` unless `TAMAGUI_HEADLESS` is set.

// Styling Text

---

To style the `title`, `subTitle`, or general `children` text, use `styled(ListItem, { ... })` to target nested `ListItem.Title`, `ListItem.Subtitle`, or `ListItem.Text` components, or compose your own with these parts. Direct text styling props are not passed for simplicity and performance.

ListItem.Apply

A context provider that passes color, size, and variant to all ListItem children.

Props

color

ColorTokens | string

Color token to pass to icons in children ListItems.

size

SizeTokens

Size token to apply to children ListItems.

variant

'outlined'

Variant to apply to children ListItems.

Anchor

Edit this page on GitHub.