ListItem

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 @hanzo/gui, or you can install it independently:

npm install @hanzogui/list-item

Usage

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

import { ListItem, Separator, YGroup } from '@hanzo/gui'
import { ChevronRight } from '@hanzogui/lucide-icons-2' // 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 '@hanzo/gui'

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 '@hanzo/gui'
import { User } from '@hanzogui/lucide-icons-2'

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 '@hanzo/gui'
import { Star, Settings } from '@hanzogui/lucide-icons-2'

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 '@hanzo/gui'

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 '@hanzo/gui'
import { Trash } from '@hanzogui/lucide-icons-2'

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, Hanzo GUI exports the building blocks: ListItem.Frame, ListItem.Text, ListItem.Title, ListItem.Subtitle, and ListItem.Icon.

import { YStack, ListItem as Hanzo GUIListItem } from '@hanzo/gui'
import { GetProps, styled } from '@hanzogui/web'

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

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

const CustomSubtitle = styled(GuiListItem.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 && <GuiListItem.Icon>{icon}</GuiListItem.Icon>}
      <YStack flex={1} justify="center">
        {title && <CustomTitle>{title}</CustomTitle>}
        {subTitle && <CustomSubtitle>{subTitle}</CustomSubtitle>}
        {children && <GuiListItem.Text>{children}</GuiListItem.Text>}
      </YStack>
      {/* iconAfter could go here */}
    </CustomFrame>
  )
}

API Reference

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

Prop	Type	Default	Required
title	React.ReactNode	-	-
subTitle	React.ReactNode	-	-
size	SizeTokens	-	-
variant	'outlined'	-	-
icon	JSX.Element \| React.ComponentType<{ size?: number }>	-	-
iconAfter	JSX.Element \| React.ComponentType<{ size?: number }>	-	-
iconSize	SizeTokens	-	-
scaleIcon	number	-	-
disabled	boolean	-	-
unstyled	boolean	-	-
// Styling Text	---	-	-

ListItem.Apply

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

Prop	Type	Default	Required
color	ColorTokens \| string	-	-
size	SizeTokens	-	-
variant	'outlined'	-	-

ListItem.Frame

The base View component for the ListItem. Inherits Stack props.

ListItem.Text

Used for wrapping children when title or subTitle are not used. Extends SizableText.

ListItem.Title

Used for rendering the title prop. Extends SizableText.

ListItem.Subtitle

Used for rendering the subTitle prop. Extends SizableText. Its font size is automatically set to one step smaller than the ListItem's main size.

ListItem.Icon

A helper component for rendering icons within ListItem, handling size and color. Typically used internally but can be leveraged in custom compositions.

ListItem

On this page