List

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

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'),
},
}))
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>
  );
}

Proudly made inNigeria by Segun Adebayo

Deployed by â–² Vercel