Table

Table component is used to organize and display data efficiently. It renders a `<table>` element by default

Props#

Table#

`colorScheme`

Description

The visual color appearance of the component

Type

"whiteAlpha" | "blackAlpha" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "cyan" | "purple" | "pink"

Default

gray

`layout`

Type

string | number | boolean | ResponsiveArray<string | number | boolean | undefined> | Partial<Record<string, string | number | boolean | undefined>> | ((theme: Record<...>) => ResponsiveValue<...>)

`size`

Description

The size of the Table

Type

"sm" | "md" | "lg"

Default

md

`variant`

Description

The variant of the Table

Type

"simple" | "striped" | "unstyled"

Default

simple

Td#

Th#

TableCaption#

`placement`

Description

The placement of the table caption. This sets the `caption-side` CSS attribute.

Type

"bottom" | "top"

Default

bottom

The Table component and its containing components are a multipart component. Styling needs to be applied to each specific part.

The TableContainer component is a single part component. Styling is applied directly to the component.

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

Table Anatomy#

A: table: The main table
B: thead: A group of table rows which label the table's columns
C: tbody: A group of table rows which contain data
D: tfoot: A group of table rows which summarize table data
D: tr: A row of table cells (td or th)
E: th: A table cell which labels a group of other table cells
F: td: A data-containing table cell
G: caption: The table's title

Theming utilities#

The following examples use theme utility functions to help define the table theme. These steps are included in all the examples below but are omitted from the specific examples to avoid repeating information.

Import the tableAnatomy object from @chakra-ui/anatomy
Import createMultiStyleConfigHelpers, and for some examples, defineStyle, from @chakra-ui/react, which provides a set of utilities for defining styles.
Destructure definePartsStyle and defineMultiStyleConfig from createMultiStyleConfigHelpers. These utility functions define style configurations for multipart components.

Customizing the default Table theme#

Use the definePartsStyle function to create a multipart style object with your base style customizations.
Use the defineMultiStyleConfig function to create a multipart component style theme configuration with customized base style.
Import the table theme into your theme file's components property.

Steps 1-2 example

import { tableAnatomy } from '@chakra-ui/anatomy'
import { createMultiStyleConfigHelpers } from '@chakra-ui/react'

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

const baseStyle = definePartsStyle({
  // define the part you're going to style
  td: {
    fontFamily: 'mono', // change the font family
    color: 'teal.500', // change the td text color
  },
})

export const tableTheme = defineMultiStyleConfig({ baseStyle })

Step 3 example

Step 3 is a crucial step to make sure that any changes that we make to the table theme are applied.

import { extendTheme } from '@chakra-ui/react'
import { tableTheme } from './components/table.ts'

export const theme = extendTheme({
  components: { Table: tableTheme },
})

Theming properties#

variant: The visual variant of the table. Defaults to simple.
colorScheme: The color scheme of the table. Defaults to gray.
size: The size of the table. Defaults to md.

Adding a custom table size#

To add an xl size to the table, add a new size to the table theme's sizes.

Use the defineStyle function to create the style for the xl size.
Use the definePartsStyle function to create a multipart style object with your new size, and define it for different component parts.
Use the defineMultiStyleConfig function to create a multipart component style theme configuration with customized size.
Import the table theme into your theme file's components property.
Run the CLI tool to update your IDE's autocomplete recognition of the new size. Learn more about the CLI tool here.

Steps 1-3 example

import { tableAnatomy } from '@chakra-ui/anatomy'
import { createMultiStyleConfigHelpers, defineStyle } from '@chakra-ui/react'

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

const xl = defineStyle({
  fontSize: 'lg',
  px: '4',
  h: '12',
})

const sizes = {
  xl: definePartsStyle({ th: xl, td: xl, caption: xl }),
}

export const tableTheme = defineMultiStyleConfig({ sizes })

Step 4 example

import { extendTheme } from '@chakra-ui/react'
import { tableTheme } from './components/table.ts'

export const theme = extendTheme({
  components: { Table: tableTheme },
})

Example utilizing the new size in a component

import { Table, Thead, Tbody, Tr, Th, Td } from '@chakra-ui/react'
function Table() {
  return (
    // Using new size in application
    <Table size='xl'>
      <Thead>
        <Tr>
          <Th>Month</Th>
          <Th>Savings</Th>
        </Tr>
      </Thead>
      <Tbody>
        <Tr>
          <Td>January</Td>
          <Td>$100</Td>
        </Tr>
      </Tbody>
    </Table>
  )
}

Adding a custom table variant#

To add a rounded variant to the table, add a new variant to the table theme's variants.

Use the definePartsStyle function to create a multipart style object with your new variant.
Use the defineMultiStyleConfig function to create a multipart component style theme configuration with custom variant.
Import the table theme into your theme file's components property.
Run the CLI tool to update your IDE's autocomplete recognition of the new size. Learn more about the CLI tool here.

Steps 1-2 example

import { tableAnatomy } from '@chakra-ui/anatomy'
import { createMultiStyleConfigHelpers } from '@chakra-ui/react'

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

const variantRounded = definePartsStyle((props) => {
  const { colorScheme: c, colorMode } = props

  return {
    tr: {
      'td:first-child': {
        borderTopLeftRadius: 'full',
        borderBottomLeftRadius: 'full',
      },
      'td:last-child': {
        borderTopRightRadius: 'full',
        borderBottomRightRadius: 'full',
      },
    },
    th: {
      '&[data-is-numeric=true]': {
        textAlign: 'end',
      },
    },
    td: {
      '&[data-is-numeric=true]': {
        textAlign: 'end',
      },
    },
    caption: {
      color: colorMode === 'light' ? `${c}.600` : `${c}.100`,
    },
    tbody: {
      tr: {
        '&:nth-of-type(odd)': {
          'th, td': {
            borderBottomWidth: '1px',
            borderColor: colorMode === 'light' ? `${c}.100` : `${c}.700`,
          },
          td: {
            background: colorMode === 'light' ? `${c}.100` : `${c}.700`,
          },
        },
        '&:nth-of-type(even)': {
          'th, td': {
            borderBottomWidth: '1px',
            borderColor: colorMode === 'light' ? `${c}.300` : `${c}.600`,
          },
          td: {
            background: colorMode === 'light' ? `${c}.300` : `${c}.600`,
          },
        },
      },
    },
    tfoot: {
      tr: {
        '&:last-of-type': {
          th: { borderBottomWidth: 0 },
        },
      },
    },
  }
})

export const tableTheme = defineMultiStyleConfig({
  variants: { variantRounded },
})

Step 3 example

import { extendTheme } from '@chakra-ui/react'
import { tableTheme } from './components/table.ts'

export const theme = extendTheme({
  components: { Table: tableTheme },
})

Example utilizing the new variant in a component

import { Table, Thead, Tbody, Tr, Th, Td } from '@chakra-ui/react'
function Table() {
  return (
    <TableContainer width={{ base: 'full', md: '25%' }} mx='auto'>
      {/* Using new variant in application */}
      <Table variant='bubble' size='sm'>
        <TableCaption placement='top'>Spending By Month</TableCaption>
        <Thead>
          <Tr>
            <Th>Month</Th>
            <Th isNumeric>Spending</Th>
          </Tr>
        </Thead>
        <Tbody>
          <Tr>
            <Td>January</Td>
            <Td isNumeric>100</Td>
          </Tr>
          <Tr>
            <Td>February</Td>
            <Td isNumeric>100</Td>
          </Tr>
        </Tbody>
        <Tfoot>
          <Tr>
            <Td>Total</Td>
            <Td isNumeric>200</Td>
          </Tr>
        </Tfoot>
      </Table>
    </TableContainer>
  )
}

Changing default table properties#

To change the default variant and size used for every Table component, change the component's defaultProps. This prevents the need to repeat setting the same size or variant each time a Table component is used.

Instead of using <Table variant="rounded" size="xl" ... /> each time you create a table, you can use <Table ... /> and the rounded variant and xl size will be applied by default.

import { tableAnatomy } from '@chakra-ui/anatomy'
import { createMultiStyleConfigHelpers } from '@chakra-ui/react'

const { defineMultiStyleConfig } = createMultiStyleConfigHelpers(
  tableAnatomy.keys,
)

export const tableTheme = defineMultiStyleConfig({
  defaultProps: {
    size: 'xl',
    variant: 'rounded',
  },
})

Showcase#

import { Box, SimpleGrid, IconButton, useColorMode, TableContainer, Table, Tr, Td, Th, Thead, Tbody, Tfoot, TableCaption, } from "@chakra-ui/react";
import { FaMoon, FaSun, FaPhone } from "react-icons/fa";

export default function App() {
  const { toggleColorMode, colorMode } = useColorMode();
  return (
    <Box position="relative" h="100vh">
      <TableContainer padding="1rem">
        <Table>
          <TableCaption placement="top">XL Size Rounded Variant Table</TableCaption>
          <Thead>
            <Tr><Th>Month</Th><Th isNumeric>Spend</Th></Tr>
          </Thead>
          <Tbody>
            <Tr><Td>January</Td><Td isNumeric>100</Td></Tr>
            <Tr><Td>February</Td><Td isNumeric>100</Td></Tr>
            <Tr><Td>March</Td><Td isNumeric>100</Td></Tr>
            <Tr><Td>April</Td><Td isNumeric>100</Td></Tr>
          </Tbody>
          <Tfoot>
            <Tr><Th>Total</Th><Th isNumeric>400</Th></Tr>
          </Tfoot>
        </Table>
      </TableContainer>
      
      <TableContainer padding="1rem">
        <Table variant="striped" size="sm">
          <TableCaption placement="top">Size: Small, Variant: Striped</TableCaption>
          <Thead>
            <Tr><Th>Month</Th><Th isNumeric>Spend</Th></Tr>
          </Thead>
          <Tbody>
            <Tr><Td>January</Td><Td isNumeric>100</Td></Tr>
            <Tr><Td>February</Td><Td isNumeric>100</Td></Tr>
            <Tr><Td>March</Td><Td isNumeric>100</Td></Tr>
            <Tr><Td>April</Td><Td isNumeric>100</Td></Tr>
          </Tbody>
          <Tfoot>
            <Tr><Th>Total</Th><Th isNumeric>400</Th></Tr>
          </Tfoot>
        </Table>
      </TableContainer>

      <IconButton
        aria-label="toggle theme"
        rounded="full"
        size="xs"
        position="fixed"
        top={4}
        left={4}
        onClick={toggleColorMode} icon={colorMode === "dark" ? <FaSun /> : <FaMoon />}
      />
    </Box>
  );
}

Open Sandbox

Edit this page on GitHub