GitHub
wwwwwwwwwwwwwwwwwww

ListItem

A simple, sizable list item

yarnnpmbunpnpm
import { ChevronRight, Cloud, Moon, Star, Sun } from '@tamagui/lucide-icons'

import { ListItem, Separator, XStack, YGroup } from 'tamagui'



export function ListItemDemo() {

  return (

    <XStack $sm={{ flexDirection: 'column' }} paddingHorizontal="$4" space>

      <ListItemDemo1 />

      <ListItemDemo2 />

    </XStack>

  )

}



function ListItemDemo1() {

  return (

    <YGroup alignSelf="center" bordered width={240} size="$4">

      <YGroup.Item>

        <ListItem hoverTheme icon={Star} title="Star" subTitle="Twinkles" />

      </YGroup.Item>

      <YGroup.Item>

        <ListItem hoverTheme icon={Moon}>

          Moon

        </ListItem>

      </YGroup.Item>

      <YGroup.Item>

        <ListItem hoverTheme icon={Sun}>

          Sun

        </ListItem>

      </YGroup.Item>

      <YGroup.Item>

        <ListItem hoverTheme icon={Cloud}>

          Cloud

        </ListItem>

      </YGroup.Item>

    </YGroup>

  )

}



function ListItemDemo2() {

  return (

    <YGroup alignSelf="center" bordered width={240} size="$5" separator={<Separator />}>

      <YGroup.Item>

        <ListItem
          hoverTheme
          pressTheme
          title="Star"
          subTitle="Subtitle"
          icon={Star}
          iconAfter={ChevronRight}
        />

      </YGroup.Item>

      <YGroup.Item>

        <ListItem
          hoverTheme
          pressTheme
          title="Moon"
          subTitle="Subtitle"
          icon={Moon}
          iconAfter={ChevronRight}
        />

      </YGroup.Item>

    </YGroup>

  )

}

Features

  • Accepts size prop that works on all styles.

  • Place an icon before or after.

  • Works with themes, animations, Group.

Installation

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

yarn add @tamagui/list-item

Usage

import { ListItem } from 'tamagui'



export default () => <ListItem>Lorem ipsum</ListItem>

Sizing

Sizing listItems provides a unique challenge especially for a compiler, because you need to adjust many different properties - not just on the outer frame, but on the text wrapped inside. Tamagui supports adjusting the padding, border radius, font size and icons sizes all in one with the size prop.

import { ListItem } from 'tamagui'



export default () => <ListItem size="$6">Lorem ipsum</ListItem>

Given your theme defines a size 6, the listItem will adjust all of the properties appropriately. You can also pass a plain number to get an arbitrary size.

Icon Theming

You can pass icons as either elements or components. If passing components, Tamagui will automatically pass the size and color prop to them based on your theme.

Customization

ListItem only supports a limited subset of text props directly, and doesn't accept hoverStyle text props. If you need more control, you can do a simple customization:

import { forwardRef } from 'react'

import {

  ListItemFrame,

  ListItemText,

  ListItemTitle,

  ListItemSubtitle,

  styled,

  themeable,

  useListItem,

} from 'tamagui'



const CustomListItemFrame = styled(ListItemFrame, {

  backgroundColor: 'orange', // or "$color", etc.

})



const CustomListItemTitle = styled(ListItemTitle, {

  color: 'blue',

})



const CustomListItemSubtitle = styled(ListItemSubtitle, {

  color: 'pink',

})



const CustomListItemText = styled(ListItemText, {

  color: 'red',

})



export const ListItem = CustomListItemFrame.styleable((propsIn, ref) => {

  const { props } = useListItem(propsIn, {

    Title: CustomListItemTitle,

    Text: CustomListItemText,

    Subtitle: CustomListItemSubtitle,

  })



  return <CustomListItemFrame {...props} ref={ref} />

})

There are 3 different components you can customize: ListItemText, ListItemSubtitle and ListItemTitle.

You can include whichever one you want to customize specifically.

If you only want to customize the the text pieces, you don't have to include CustomListItemFrame:

// all the text changes from above, with a default ListItemFrame

export const ListItem = themeable(

  forwardRef<TamaguiElement, ListItemProps>((propsIn, ref) => {

    const { props } = useListItem(propsIn, {

      Title: CustomListItemTitle,

      Text: CustomListItemText,

      Subtitle: CustomListItemSubtitle,

    })



    return <ListItemFrame {...props} ref={ref} />

  })

)

API Reference

ListItem

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

Props

  • title

    React.ReactNode

    Can use either children or title + subTitle to set the contents.

  • subTitle

    React.ReactNode

    Sets a subTitle, recommended to use with title.

  • size

    string | tokens.size

    Set a size, number or one of the size token values.

  • theme

    string

    Apply a theme just to the listItem and it's children

  • themeInverse

    boolean

    Helpful for "flipping" any theme between dark and light (including flipping a sub themes defined as [subtheme]-[dark/light]

  • noTextWrap

    boolean

    If true, ListItem won't wrap content with a Text element.

  • icon

    JSX.Element

    Pass any React element, appears before the text.

  • iconAfter

    JSX.Element

    Pass any React element, appears after the text.

  • scaleIcon

    number

    Scale the icon more than usual by this number.

  • scaleSpace

    number

    Scale the spacing more than usual by this number.

  • spaceFlex

    boolean

    Makes all space elements have a flex.

  • color

    SizableTextProps['color']

    Passes "color" down to the inner text component

  • fontWeight

    SizableTextProps['fontWeight']

    Passes "fontWeight" down to the inner text component

  • letterSpacing

    SizableTextProps['letterSpacing']

    Passes "letterSpacing" down to the inner text component

  • textAlign

    SizableTextProps['textAlign']

    Passes "textAlign" down to the inner text component

  • unstyled

    boolean

    Removes all default Tamagui styles.

    • ListItem.Title

    ListItem.Title extend SizableText inheriting all the props.

    ListItem.Subtitle

    ListItem.Subtitle extend SizableText inheriting all the props.

    ListItem.Text

    ListItem.Text extend SizableText inheriting all the props. */}

    Previous

    Image

    Next

    LinearGradient

    Edit this page on GitHub.