List

List is a semantic list component for displaying ordered or unordered items.

Open in Storybook

Import

import { List, ListItem, ListIcon } from "@tosui/react";

Basic usage

Preview

Code

<List>
  <ListItem>First item</ListItem>
  <ListItem>Second item</ListItem>
  <ListItem>Third item</ListItem>
</List>

Ordered list

Preview

1. Step one
2. Step two
3. Step three

Code

<List as="ol">
  <ListItem>Step one</ListItem>
  <ListItem>Step two</ListItem>
  <ListItem>Step three</ListItem>
</List>

Style types

Preview

None (default for ul)

• Item without bullet
• Another item

Disc

• Item with bullet
• Another item

Decimal (default for ol)

1. Numbered item
2. Another item

Code

<VStack gap={6} align="start">
  <Box>
    <Box fontWeight="medium" mb={2}>None (default for ul)</Box>
    <List styleType="none">
      <ListItem>Item without bullet</ListItem>
      <ListItem>Another item</ListItem>
    </List>
  </Box>

  <Box>
    <Box fontWeight="medium" mb={2}>Disc</Box>
    <List styleType="disc">
      <ListItem>Item with bullet</ListItem>
      <ListItem>Another item</ListItem>
    </List>
  </Box>

  <Box>
    <Box fontWeight="medium" mb={2}>Decimal (default for ol)</Box>
    <List as="ol" styleType="decimal">
      <ListItem>Numbered item</ListItem>
      <ListItem>Another item</ListItem>
    </List>
  </Box>
</VStack>

Spacing

Preview

No spacing (default)

• First item
• Second item
• Third item

With spacing

• First item
• Second item
• Third item

Code

<VStack gap={6}>
  <Box>
    <Box fontWeight="medium" mb={2}>No spacing (default)</Box>
    <List styleType="disc" spacing={0}>
      <ListItem>First item</ListItem>
      <ListItem>Second item</ListItem>
      <ListItem>Third item</ListItem>
    </List>
  </Box>

  <Box>
    <Box fontWeight="medium" mb={2}>With spacing</Box>
    <List styleType="disc" spacing={2}>
      <ListItem>First item</ListItem>
      <ListItem>Second item</ListItem>
      <ListItem>Third item</ListItem>
    </List>
  </Box>
</VStack>

With icons

Use ListIcon to add custom icons to list items.

import { CheckIcon, StarIcon } from "your-icon-library";

<List spacing={2}>
  <ListItem>
    <ListIcon><CheckIcon /></ListIcon>
    Feature one
  </ListItem>
  <ListItem>
    <ListIcon><CheckIcon /></ListIcon>
    Feature two
  </ListItem>
  <ListItem>
    <ListIcon><StarIcon /></ListIcon>
    Premium feature
  </ListItem>
</List>

Common patterns

Feature list

<List spacing={3}>
  <ListItem>
    <ListIcon><CheckIcon /></ListIcon>
    Unlimited users
  </ListItem>
  <ListItem>
    <ListIcon><CheckIcon /></ListIcon>
    API access
  </ListItem>
  <ListItem>
    <ListIcon><CheckIcon /></ListIcon>
    24/7 support
  </ListItem>
  <ListItem>
    <ListIcon><CheckIcon /></ListIcon>
    Custom integrations
  </ListItem>
</List>

Steps

<List as="ol" spacing={4}>
  <ListItem>
    <Box>
      <Box fontWeight="medium">Create an account</Box>
      <Text size="sm" color="foreground-muted">
        Sign up with your email address
      </Text>
    </Box>
  </ListItem>
  <ListItem>
    <Box>
      <Box fontWeight="medium">Verify your email</Box>
      <Text size="sm" color="foreground-muted">
        Click the link in your inbox
      </Text>
    </Box>
  </ListItem>
  <ListItem>
    <Box>
      <Box fontWeight="medium">Complete your profile</Box>
      <Text size="sm" color="foreground-muted">
        Add your details and preferences
      </Text>
    </Box>
  </ListItem>
</List>

Props reference

List

Prop	Type	Default	Description
as	"ul" | "ol"	"ul"	HTML list element
styleType	"none" | "disc" | "decimal"	depends on as	List style type
spacing	number	0	Gap between items (spacing multiplier)
className	string	-	Additional CSS class
children	ReactNode	-	List items

ListItem

Prop	Type	Default	Description
children	ReactNode	-	Item content
className	string	-	Additional CSS class

ListIcon

Prop	Type	Default	Description
children	ReactNode	-	Icon content
className	string	-	Additional CSS class

TypeScript

import { List, ListItem, ListIcon, type ListStyleType, type ListProps, type ListItemProps, type ListIconProps } from "@tosui/react";