Table

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

Import#

import { Table } from '@chakra-ui/react'

Usage#

<Table.Root>
  <Table.Header>
    <Table.Row>
      <Table.ColumnHeader>Name</Table.ColumnHeader>
      <Table.ColumnHeader>Email</Table.ColumnHeader>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Segun Adebayo</Table.Cell>
      <Table.Cell>sage@acme.org </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>Sally Thompson</Table.Cell>
      <Table.Cell>sally@acme.org</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table.Root>

Driving the table with data#

To render a table with data, you can use the map function to iterate over the data and render the table rows.

const data = [
  { id: 1, name: 'John Doe', age: 25, gender: 'Male' },
  { id: 2, name: 'Jane Smith', age: 30, gender: 'Female' },
  { id: 3, name: 'Michael Johnson', age: 35, gender: 'Male' },
  { id: 4, name: 'Emily Davis', age: 28, gender: 'Female' },
  { id: 5, name: 'David Brown', age: 32, gender: 'Male' },
]

function Demo() {
  const rows = data.map((row) => (
    <Table.Row key={row.id}>
      <Table.Cell>{row.name}</Table.Cell>
      <Table.Cell numeric>{row.age}</Table.Cell>
      <Table.Cell>{row.gender}</Table.Cell>
    </Table.Row>
  ))

  return (
    <Table.Root>
      <Table.Header>
        <Table.Row>
          <Table.ColumnHeader>Name</Table.ColumnHeader>
          <Table.ColumnHeader numeric>Age</Table.ColumnHeader>
          <Table.ColumnHeader>Gender</Table.ColumnHeader>
        </Table.Row>
      </Table.Header>
      <Table.Body>{rows}</Table.Body>
    </Table.Root>
  )
}

render(<Demo />)

Changing the table variant#

The table component comes in 2 variants: line and outline

<Table.Root variant='outline'>
  <Table.Header>
    <Table.Row>
      <Table.ColumnHeader>To convert</Table.ColumnHeader>
      <Table.ColumnHeader>into</Table.ColumnHeader>
      <Table.ColumnHeader numeric>multiply by</Table.ColumnHeader>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>inches</Table.Cell>
      <Table.Cell>millimetres (mm)</Table.Cell>
      <Table.Cell numeric>25.4</Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>feet</Table.Cell>
      <Table.Cell>centimetres (cm)</Table.Cell>
      <Table.Cell numeric>30.48</Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>yards</Table.Cell>
      <Table.Cell>metres (m)</Table.Cell>
      <Table.Cell numeric>0.91444</Table.Cell>
    </Table.Row>
  </Table.Body>
  <Table.Footer>
    <Table.Row>
      <Table.Cell>To convert</Table.Cell>
      <Table.Cell>into</Table.Cell>
      <Table.Cell numeric>multiply by</Table.Cell>
    </Table.Row>
  </Table.Footer>
</Table.Root>

Changing the table size#

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

<For each={['sm', 'md', 'lg']}>
  {(size) => (
    <Table.Overflow key={size} mb='10'>
      <Table.Root size={size}>
        <Table.Header>
          <Table.Row>
            <Table.ColumnHeader>Name</Table.ColumnHeader>
            <Table.ColumnHeader>Email</Table.ColumnHeader>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          <Table.Row>
            <Table.Cell>Segun Adebayo</Table.Cell>
            <Table.Cell>sage@acme.org </Table.Cell>
          </Table.Row>
          <Table.Row>
            <Table.Cell>Sally Thompson</Table.Cell>
            <Table.Cell>sally@acme.org</Table.Cell>
          </Table.Row>
        </Table.Body>
      </Table.Root>
    </Table.Overflow>
  )}
</For>

Handling overflow in tables#

Tables can be quite large and can overflow the parent container. To handle overflow, you can wrap the table in a Table.Overflow component.

Performance optimization in large tables#

Due to the limitations of the DOM combined with CSS-in-JS, large tables can be slow to render. To optimize style performance, pass the native prop to the Table.Root component and render the table using native HTML elements.

<Table.Root native>
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Segun Adebayo</td>
      <td>sage@acme.org </td>
    </tr>
    <tr>
      <td>Sally Thompson</td>
      <td>sally@acme.org</td>
    </tr>
  </tbody>
</Table.Root>

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