gui/apps/gui.hanzo.ai/data/docs/components/list-item/1.0.0.mdx

---
title: ListItem
description: A component for showing columns of items.
name: list-item
component: ListItem
package: list-item
demoName: ListItem
---

<HeroContainer>
  <ListItemDemo />
</HeroContainer>

```tsx hero template=ListItem

```

<Highlights
  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 `hanzogui`, or you can install it independently:

```bash
npm install @hanzogui/list-item
```

## Usage

```tsx
import { ListItem } from '@hanzo/gui'

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. Gui supports adjusting the padding, border radius, font size and icons sizes all in one with the `size` prop.

```tsx
import { ListItem } from '@hanzo/gui'

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, Gui 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:

```tsx
import { forwardRef } from 'react'
import {
  ListItemFrame,
  ListItemText,
  ListItemTitle,
  ListItemSubtitle,
  styled,
  themeable,
  useListItem,
} from '@hanzo/gui'

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`:

```tsx
// all the text changes from above, with a default ListItemFrame
export const ListItem = themeable(
  forwardRef<GuiElement, 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 [Gui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'title',
      required: false,
      type: 'React.ReactNode',
      description: `Can use either children or title + subTitle to set the contents.`,
    },
    {
      name: 'subTitle',
      required: false,
      type: 'React.ReactNode',
      description: `Sets a subTitle, recommended to use with title.`,
    },
    {
      name: 'size',
      required: false,
      type: 'string | tokens.size',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'theme',
      required: false,
      type: 'string',
      description: `Apply a theme just to the listItem and it's children`,
    },
    {
      name: 'themeInverse',
      required: false,
      type: 'boolean',
      description: `Helpful for "flipping" any theme between dark and light (including flipping a sub themes defined as [subtheme]-[dark/light]`,
    },
    {
      name: 'noTextWrap',
      required: false,
      type: 'boolean',
      description: `If true, ListItem won't wrap content with a Text element.`,
    },
    {
      name: 'icon',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears before the text.`,
    },
    {
      name: 'iconAfter',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears after the text.`,
    },
    {
      name: 'scaleIcon',
      required: false,
      type: 'number',
      description: `Scale the icon more than usual by this number.`,
    },
    {
      name: 'scaleSpace',
      required: false,
      type: 'number',
      description: `Scale the spacing more than usual by this number.`,
    },
    {
      name: 'spaceFlex',
      required: false,
      type: `boolean`,
      description: `Makes all space elements have a flex.`,
    },
    {
      name: 'color',
      required: false,
      type: `SizableTextProps['color']`,
      description: `Passes "color" down to the inner text component`,
    },
    {
      name: 'fontWeight',
      required: false,
      type: `SizableTextProps['fontWeight']`,
      description: `Passes "fontWeight" down to the inner text component`,
    },
    {
      name: 'letterSpacing',
      required: false,
      type: `SizableTextProps['letterSpacing']`,
      description: `Passes "letterSpacing" down to the inner text component`,
    },
    {
      name: 'textAlign',
      required: false,
      type: `SizableTextProps['textAlign']`,
      description: `Passes "textAlign" down to the inner text component`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Gui styles.`,
    },
  ]}
/>

### ListItem.Title

`ListItem.Title` extend `SizableText` inheriting all the [props](/docs/components/text#sizabletext).

### ListItem.Subtitle

`ListItem.Subtitle` extend `SizableText` inheriting all the [props](/docs/components/text#sizabletext).

### ListItem.Text

`ListItem.Text` extend `SizableText` inheriting all the [props](/docs/components/text#sizabletext).