List

List is used to display list items. It renders a <ul> element by default.

Import#

import {
  List,
  ListItem,
  ListIcon,
  OrderedList,
  UnorderedList,
} from '@chakra-ui/react'

Unordered List#

<UnorderedList>
  <ListItem>Lorem ipsum dolor sit amet</ListItem>
  <ListItem>Consectetur adipiscing elit</ListItem>
  <ListItem>Integer molestie lorem at massa</ListItem>
  <ListItem>Facilisis in pretium nisl aliquet</ListItem>
</UnorderedList>

Ordered List#

<OrderedList>
  <ListItem>Lorem ipsum dolor sit amet</ListItem>
  <ListItem>Consectetur adipiscing elit</ListItem>
  <ListItem>Integer molestie lorem at massa</ListItem>
  <ListItem>Facilisis in pretium nisl aliquet</ListItem>
</OrderedList>

Unstyled List with icon#

Add icons to the list items by using the ListIcon component. You can pass the name of the icon or use custom icons. The size of the icon is relative to the font size of the list item.

<List spacing={3}>
  <ListItem>
    <ListIcon as={MdCheckCircle} color='green.500' />
    Lorem ipsum dolor sit amet, consectetur adipisicing elit
  </ListItem>
  <ListItem>
    <ListIcon as={MdCheckCircle} color='green.500' />
    Assumenda, quia temporibus eveniet a libero incidunt suscipit
  </ListItem>
  <ListItem>
    <ListIcon as={MdCheckCircle} color='green.500' />
    Quidem, ipsam illum quis sed voluptatum quae eum fugit earum
  </ListItem>
  {/* You can also use custom icons from react-icons */}
  <ListItem>
    <ListIcon as={MdSettings} color='green.500' />
    Quidem, ipsam illum quis sed voluptatum quae eum fugit earum
  </ListItem>
</List>

Custom style type#

Sometimes we need to specify our own marker in lists using the built-in capabilities of the browser. In css this can be done using the CSS property list-style-type.

To do the same in List, you can use the prop styleType.

For example:

<UnorderedList styleType='lower-roman'>
  <ListItem>Lorem ipsum dolor sit amet</ListItem>
  <ListItem>Consectetur adipiscing elit</ListItem>
  <ListItem>Integer molestie lorem at massa</ListItem>
  <ListItem>Facilisis in pretium nisl aliquet</ListItem>
</UnorderedList>

In fact, the content that you pass to styleType will become the value of the list-style-type property.

That is, you can represent styleType='lower-roman' as list-style-type: lower-roman;.

If you need to make a custom marker from a string, for example -, this can be done as follows:

<UnorderedList styleType="'-'">
  <ListItem>Lorem ipsum dolor sit amet</ListItem>
  <ListItem>Consectetur adipiscing elit</ListItem>
  <ListItem>Integer molestie lorem at massa</ListItem>
  <ListItem>Facilisis in pretium nisl aliquet</ListItem>
</UnorderedList>

It is important to understand that UnorderedList, OrderedList and List work the same in this case.

The List component is a multipart component. The styling needs to be applied to each part specifically.

To learn more about styling multipart components, visit the Component Style page.

Anatomy#

A: container
B: item
C: icon

Theming properties#

The properties that affect the theming of the List component are:

size: The size of the list.
variant: The visual variant of the list
colorScheme: The color scheme of the list.

Theming utilities#

createMultiStyleConfigHelpers: a function that returns a set of utilities for creating style configs for a multipart component (definePartsStyle and defineMultiStyleConfig).
definePartsStyle: a function used to create multipart style objects.
defineMultiStyleConfig: a function used to define the style configuration for a multipart component.

import { listAnatomy as parts } from '@chakra-ui/anatomy'
import { createMultiStyleConfigHelpers } from '@chakra-ui/react'

const { definePartsStyle, defineMultiStyleConfig } =
  createMultiStyleConfigHelpers(parts.keys)

Customizing the default theme#

import {
  defineStyle,
  createMultiStyleConfigHelpers,
} from '@chakra-ui/styled-system'
import { listAnatomy as parts } from '@chakra-ui/anatomy'
import { mode } from '@chakra-ui/theme-tools'

const { definePartsStyle, defineMultiStyleConfig } =
  createMultiStyleConfigHelpers(parts.keys)

const baseStyle = definePartsStyle((props) => ({
  // define the part you're going to style
  container: {
    listStylePos: 'inside', // change listStylePos to inside
    boxShadow: 'md', // change boxShadow to md
  },
  item: {
    p: 2, // set padding to 2
    '&::marker': {
      // change color for marker
      color: mode('green.500', 'green.200')(props),
    },
  },
  icon: {
    //change color for icon
    color: mode('blue.500', 'blue.200')(props),
  },
}))

export const listTheme = defineMultiStyleConfig({ baseStyle })

After customizing the list theme, we can import it in our theme file and add it in the components property:

import { extendTheme } from '@chakra-ui/react'
import { listTheme } from './theme/components/list.ts'
export const theme = extendTheme({
  components: { List: listTheme },
})

This is a crucial step to make sure that any changes that we make to the list theme are applied.

Adding a custom size#

Let's assume we want to include an extra large list size. Here's how we can do that:

import {
  defineStyle,
  createMultiStyleConfigHelpers,
} from '@chakra-ui/styled-system'
import { listAnatomy as parts } from '@chakra-ui/anatomy'

const { definePartsStyle, defineMultiStyleConfig } =
  createMultiStyleConfigHelpers(parts.keys)

const sizes = {
  xl: definePartsStyle({
    container: defineStyle({
      fontSize: 'xl',
      p: 6,
    }),
    icon: defineStyle({
      boxSize: 6,
      mr: 5,
    }),
  }),
}
export const listTheme = defineMultiStyleConfig({ sizes })
// Now we can use the new `xl` size
<List size="xl">...</List>

Creating a custom variant#

import {
  defineStyle,
  createMultiStyleConfigHelpers,
} from '@chakra-ui/styled-system'
import { listAnatomy as parts } from '@chakra-ui/anatomy'
import { mode } from '@chakra-ui/theme-tools'

const { definePartsStyle, defineMultiStyleConfig } =
  createMultiStyleConfigHelpers(parts.keys)

const variants = {
  custom: definePartsStyle((props) => ({
    container: {
      bg: mode('white', 'gray.700')(props),
    },
    item: {
      borderBottom: '1px solid',
      '&::marker': {
        color: mode('cyan.500', 'cyan.200')(props),
      },
    },
  })),
}

export const listTheme = defineMultiStyleConfig({ variants })
// Now we can use the new `custom` variant
<List varint="custom">...</List>

Changing the default properties#

Let's assume we want to change the default size and variant of every list in our app. Here's how we can do that:

import {
  defineStyle,
  createMultiStyleConfigHelpers,
} from '@chakra-ui/styled-system'
import { listAnatomy as parts } from '@chakra-ui/anatomy'

const { defineMultiStyleConfig } = createMultiStyleConfigHelpers(parts.keys)

export const listTheme = defineMultiStyleConfig({
  defaultProps: {
    size: 'xl',
    variant: 'custom',
  },
})
// This saves you time, instead of manually setting the size and variant every time you use a list:
<List size="xl" variant="custom"></List>

Showcase#

import {
  Box,
  IconButton,
  List,
  ListIcon,
  ListItem,
  OrderedList,
  UnorderedList,
  useColorMode,
  Text,
  SimpleGrid,
  Checkbox,
} from "@chakra-ui/react";
import { FaMoon, FaSun } from "react-icons/fa";
import { MdCheckCircle, MdSettings, MdOutlineSell } from "react-icons/md";

export default function App() {
  const { toggleColorMode, colorMode } = useColorMode();

  return (
    <Box position="relative" h="100vh">
      <SimpleGrid gap={12} p={12} columns={3}>
        <Box>
          <OrderedList p={2}>
            <ListItem>Lorem ipsum dolor sit</ListItem>
            <ListItem>Consectetur adipiscing</ListItem>
            <ListItem>Integer molestie lorem</ListItem>
          </OrderedList>
        </Box>
        <Box>
          <UnorderedList p={2}>
            <ListItem>Lorem ipsum dolor sit</ListItem>
            <ListItem>Consectetur adipiscing</ListItem>
            <ListItem>Integer molestie lorem</ListItem>
          </UnorderedList>
        </Box>
        <Box>
          <List p={2}>
            <ListItem>
              <ListIcon as={MdCheckCircle} />
              Lorem ipsum dolor sit
            </ListItem>
            <ListItem>
              <ListIcon as={MdCheckCircle} />
              Consectetur adipiscing
            </ListItem>
            <ListItem>
              <ListIcon as={MdSettings} />
              Integer molestie lorem
            </ListItem>
          </List>
        </Box>
      </SimpleGrid>

      <SimpleGrid gap={12} px={12} columns={2}>
        <Box>
          <List size="xl" variant="custom" spacing={5}>
            <ListItem>
              <Checkbox>Lorem ipsum dolor sit</Checkbox>
              <Text color="gray.400" fontSize="xs">
                Due Date: 01/01/2023
              </Text>
            </ListItem>
            <ListItem>
              <Checkbox>Lorem ipsum dolor sit</Checkbox>
              <Text color="gray.400" fontSize="xs">
                Due Date: 01/01/2023
              </Text>
            </ListItem>
            <ListItem>
              <Checkbox>Lorem ipsum dolor sit</Checkbox>
              <Text color="gray.400" fontSize="xs">
                Due Date: 01/01/2023
              </Text>
            </ListItem>
          </List>
        </Box>
        <Box>
          <List size="xl" variant="orange" spacing={3}>
            <ListItem>
              <ListIcon as={MdOutlineSell} />
              Lorem ipsum dolor sit
            </ListItem>
            <ListItem>
              <ListIcon as={MdOutlineSell} />
              Lorem ipsum dolor sit
            </ListItem>
            <ListItem>
              <ListIcon as={MdOutlineSell} />
              Lorem ipsum dolor sit
            </ListItem>
          </List>
        </Box>
      </SimpleGrid>
      <Box>
        <IconButton
          aria-label="toggle theme"
          rounded="full"
          size="xs"
          position="fixed"
          bottom={4}
          left={4}
          onClick={toggleColorMode}
          icon={colorMode === "dark" ? <FaSun /> : <FaMoon />}
        />
      </Box>
    </Box>
  );
}

Open Sandbox

Edit this page on GitHub