List

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

Source

@chakra-ui/layout

Props#

List Props#

`spacing`

Description

The space between each list item

Type

ResponsiveValue<string | number | (string & {})>

`stylePosition`

Description

Shorthand prop for listStylePosition

Type

ResponsiveValue<ListStylePosition>

`styleType`

Description

Shorthand prop for listStyleType

Type

ResponsiveValue<ListStyleType>

List Item Props#

ListItem composes Box so you can pass all style and pseudo style props.

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