Table

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

Import#

import {
  Table,
  Thead,
  Tbody,
  Tfoot,
  Tr,
  Th,
  Td,
  TableCaption,
  TableContainer,
} from '@chakra-ui/react'

Table Container#

The table container component renders a div that wraps the table component to not allow the table to overflow the parent container, not allow data content to break lines without exception, and enable horizontal scrolling.

It renders the following props:

Property	Value
`display`	`block`
`maxWidth`	`100%`
`overflowX`	`auto`
`overflowY`	`hidden`
`whiteSpace`	`nowrap`

It can optionally accept the overflow or overflowX props to override the overflowX default value of auto rendered by this component.

This component will be shown on all examples in this page. View the examples in mobile to see the effects.

Table Variants#

The table component comes in 3 variants: simple, striped, and unstyled. The default variant is simple

Change the variant values to see the other variants.

Simple Table#

<TableContainer>
  <Table variant='simple'>
    <TableCaption>Imperial to metric conversion factors</TableCaption>
    <Thead>
      <Tr>
        <Th>To convert</Th>
        <Th>into</Th>
        <Th isNumeric>multiply by</Th>
      </Tr>
    </Thead>
    <Tbody>
      <Tr>
        <Td>inches</Td>
        <Td>millimetres (mm)</Td>
        <Td isNumeric>25.4</Td>
      </Tr>
      <Tr>
        <Td>feet</Td>
        <Td>centimetres (cm)</Td>
        <Td isNumeric>30.48</Td>
      </Tr>
      <Tr>
        <Td>yards</Td>
        <Td>metres (m)</Td>
        <Td isNumeric>0.91444</Td>
      </Tr>
    </Tbody>
    <Tfoot>
      <Tr>
        <Th>To convert</Th>
        <Th>into</Th>
        <Th isNumeric>multiply by</Th>
      </Tr>
    </Tfoot>
  </Table>
</TableContainer>

Striped Table#

<TableContainer>
  <Table variant='striped' colorScheme='teal'>
    <TableCaption>Imperial to metric conversion factors</TableCaption>
    <Thead>
      <Tr>
        <Th>To convert</Th>
        <Th>into</Th>
        <Th isNumeric>multiply by</Th>
      </Tr>
    </Thead>
    <Tbody>
      <Tr>
        <Td>inches</Td>
        <Td>millimetres (mm)</Td>
        <Td isNumeric>25.4</Td>
      </Tr>
      <Tr>
        <Td>feet</Td>
        <Td>centimetres (cm)</Td>
        <Td isNumeric>30.48</Td>
      </Tr>
      <Tr>
        <Td>yards</Td>
        <Td>metres (m)</Td>
        <Td isNumeric>0.91444</Td>
      </Tr>
    </Tbody>
    <Tfoot>
      <Tr>
        <Th>To convert</Th>
        <Th>into</Th>
        <Th isNumeric>multiply by</Th>
      </Tr>
    </Tfoot>
  </Table>
</TableContainer>

Table Sizing#

The table component is available in 3 sizes: sm, md, lg. The default size is md.

<TableContainer>
  <Table size='sm'>
    <Thead>
      <Tr>
        <Th>To convert</Th>
        <Th>into</Th>
        <Th isNumeric>multiply by</Th>
      </Tr>
    </Thead>
    <Tbody>
      <Tr>
        <Td>inches</Td>
        <Td>millimetres (mm)</Td>
        <Td isNumeric>25.4</Td>
      </Tr>
      <Tr>
        <Td>feet</Td>
        <Td>centimetres (cm)</Td>
        <Td isNumeric>30.48</Td>
      </Tr>
      <Tr>
        <Td>yards</Td>
        <Td>metres (m)</Td>
        <Td isNumeric>0.91444</Td>
      </Tr>
    </Tbody>
    <Tfoot>
      <Tr>
        <Th>To convert</Th>
        <Th>into</Th>
        <Th isNumeric>multiply by</Th>
      </Tr>
    </Tfoot>
  </Table>
</TableContainer>

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

Table

Import#

Table Container#

Table Variants#

Simple Table#

Striped Table#

Table Sizing#

Props#

Table#

`colorScheme`

`layout`

`size`

`variant`

Td#

Th#

TableCaption#

`placement`