--- title: Table description: "`Table` is a table component equipped with column sorting, row selection, and click event features." links: - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/table - storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-table--basic --- ```tsx interface Data { id: string age: number email: string firstName: string lastName: string } const columnHelper = createColumnHelper() const columns = useMemo( () => [ columnHelper.accessor("id", { cellProps: { numeric: true } }), columnHelper.accessor("firstName", { lineClamp: 1 }), columnHelper.accessor("lastName", { lineClamp: 1 }), columnHelper.accessor("age", { cellProps: { numeric: true } }), columnHelper.accessor("email", { lineClamp: 1 }), ], [], ) const data = useMemo( () => Array.from({ length: 10 }, (_, index) => ({ id: index.toString(), age: faker.number.int({ max: 65, min: 18 }), email: faker.internet.email(), firstName: faker.person.firstName(), lastName: faker.person.lastName(), })), [], ) return ``` ## Usage ```tsx import { Table } from "@yamada-ui/react" ``` ```tsx import { Table } from "@/components/ui" ``` ```tsx import { Table } from "@workspaces/ui" ``` ```tsx
``` :::note `Table` internally uses [tanstack-table](https://tanstack.com/table) and [NativeTable](https://yamada-ui.com/docs/components/native-table.md). ::: ### Change Variant ```tsx const data = useMemo(() => createData(), []) return ( {(variant, index) => (
)} ) ``` ### Change Size ```tsx const data = useMemo(() => createData(), []) return ( {(size, index) => (
)} ) ``` ### Change Color Scheme ```tsx const data = useMemo(() => createData(), []) return ( {(colorScheme, index) => (
)} ) ``` ### Add Outer Border To add an outer border, set `withBorder` to `true`. ```tsx const data = useMemo(() => createData(), []) return
``` ### Add Column Separators To add column separators, set `withColumnBorders` to `true`. ```tsx const data = useMemo(() => createData(), []) return
``` ### Highlight on Row Hover To highlight rows when hovered, set `highlightOnHover` to `true`. ```tsx const data = useMemo(() => createData(), []) return
``` ### Striped To enable striped rows, set `striped` to `true`. ```tsx const data = useMemo(() => createData(), []) return
``` ### Scroll Area To enable scroll area, set `withScrollArea` to `true`. ```tsx const data = useMemo(() => createData(), []) return
``` ### Header Groups ```tsx const columns = useMemo( () => [ columnHelper.accessor("id", { footer: (info) => info.column.id, cellProps: { numeric: true }, }), columnHelper.group({ id: "user", columns: [ columnHelper.group({ id: "name", columns: [ columnHelper.accessor("firstName", { footer: (info) => info.column.id, lineClamp: 1, }), columnHelper.accessor("lastName", { footer: (info) => info.column.id, lineClamp: 1, }), ], footer: (info) => info.column.id, header: (info) => info.column.id, }), columnHelper.accessor("age", { footer: (info) => info.column.id, cellProps: { numeric: true }, }), columnHelper.accessor("email", { footer: (info) => info.column.id, lineClamp: 1, }), ], footer: (info) => info.column.id, header: (info) => info.column.id, }), ], [], ) const data = useMemo(() => createData(), []) return (
) ``` ### Footer Groups ```tsx const columns = useMemo( () => [ columnHelper.accessor("id", { footer: (info) => info.column.id, cellProps: { numeric: true }, }), columnHelper.group({ id: "user", columns: [ columnHelper.group({ id: "name", columns: [ columnHelper.accessor("firstName", { footer: (info) => info.column.id, lineClamp: 1, }), columnHelper.accessor("lastName", { footer: (info) => info.column.id, lineClamp: 1, }), ], footer: (info) => info.column.id, header: (info) => info.column.id, }), columnHelper.accessor("age", { footer: (info) => info.column.id, cellProps: { numeric: true }, }), columnHelper.accessor("email", { footer: (info) => info.column.id, lineClamp: 1, }), ], footer: (info) => info.column.id, header: (info) => info.column.id, }), ], [], ) const data = useMemo(() => createData(), []) return (
) ``` ### Disable Keyboard Navigation To disable keyboard navigation, set `enableKeyboardNavigation` to `false`. The default is `true`. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ### Set Initial Focusable Cell To set the initial focusable cell, set `initialFocusableCell` to an object with the column and row indices (`{ colIndex: number, rowIndex: number }`). The default is `{ colIndex: 0, rowIndex: 0 }`. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ### Handle Row Click Event To handle the row click event, use `onRowClick`. ```tsx const data = useMemo(() => createData(), []) return (
console.log(row)} withScrollArea /> ) ``` ### Handle Row Double Click Event To handle the row double click event, use `onRowDoubleClick`. ```tsx const data = useMemo(() => createData(), []) return (
console.log(row)} withScrollArea /> ) ``` ### Set Default Sorting To set the default sorting, set `defaultSorting` to an array of objects with the column `id` and direction. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ### Disable Sorting To disable sorting, set `enableSorting` to `false`. The default is `true`. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ### Disable Multi Sorting To disable multi sorting, set `enableMultiSort` to `false`. The default is `true`. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ### Set Maximum Sortable Columns To set the maximum sortable columns, set `maxMultiSortColCount` to a number. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ### Manual Sorting To use manual sorting, set `manualSorting` to `true`. The default is `false`. ```tsx const defaultData = useMemo(() => createData(), []) const [data, setData] = useState(defaultData) return (
{ if (sorting.length) { const { id, desc } = sorting[0]! setData((prev) => prev.toSorted((a, b) => { if (isNumber(a[id]) && isNumber(b[id])) { return desc ? a[id] - b[id] : b[id] - a[id] } else if (isString(a[id]) && isString(b[id])) { return desc ? a[id].localeCompare(b[id]) : b[id].localeCompare(a[id]) } return 0 }), ) } else { setData(defaultData) } console.log(sorting) }} /> ) ``` ### Change Sorting Toggle By default, when sorting is enabled, it starts in ascending order. If you want to start in descending order, set `sortDescFirst` to `true`. If you want to set it only for specific columns, set `sortDescFirst` to `true` for each column in `columns`. The default is `false`. ```tsx const data = useMemo(() => createData(), []) return
``` ### Control Sorting ```tsx const [sorting, setSorting] = useState>([ { id: "age", desc: true }, ]) const data = useMemo(() => createData(), []) return
``` ### Enable Pagination To enable pagination, set `enablePagination` to `true` and set the component that controls the pagination to `header` or `footer`. The default is `false`. ```tsx const { t } = useI18n("table") const data = useMemo(() => createData(40), []) return (
{ const page = table.getState().pagination.pageIndex + 1 const pageSize = table.getState().pagination.pageSize const total = table.getPageCount() return ( table.setPageIndex(page - 1)} /> table.setPageSize(Number(value))} /> ) }} withScrollArea /> ) ``` ### Set Default Page Index and Page Size To set the default page index and page size, set `defaultPagination` to an object with the `pageIndex` and `pageSize`. ```tsx const { t } = useI18n("table") const data = useMemo(() => createData(20), []) return (
{ const page = table.getState().pagination.pageIndex + 1 const pageSize = table.getState().pagination.pageSize const total = table.getPageCount() return ( table.setPageIndex(page - 1)} /> table.setPageSize(Number(value))} /> ) }} withScrollArea /> ) ``` ### Use Manual Pagination To use manual pagination, set `manualPagination` to `true`. The default is `false`. ```tsx const { t } = useI18n("table") const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 20, }) const rowCount = 40 const defaultData = useMemo(() => createData(rowCount), []) const data = useMemo( () => defaultData.slice( pagination.pageIndex * pagination.pageSize, (pagination.pageIndex + 1) * pagination.pageSize, ), [defaultData, pagination], ) return (
{ const page = table.getState().pagination.pageIndex + 1 const pageSize = table.getState().pagination.pageSize const total = table.getPageCount() return ( table.setPageIndex(page - 1)} /> table.setPageSize(Number(value))} /> ) }} withScrollArea /> ) ``` ### Control Pagination ```tsx const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 20, }) const { t } = useI18n("table") const data = useMemo(() => createData(40), []) return (
{ const page = table.getState().pagination.pageIndex + 1 const pageSize = table.getState().pagination.pageSize const total = table.getPageCount() return ( table.setPageIndex(page - 1)} /> table.setPageSize(Number(value))} /> ) }} withScrollArea /> ) ``` ### Enable Row Selection To enable row selection, set `enableRowSelection` to `true`. The default is `false`. ```tsx const data = useMemo(() => createData(), []) return
``` ### Set Default Selected Rows To set the default selected rows, set `defaultRowSelection` to an object with the index of the `data` as the key. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ### Enable Row Selection on Click To enable row selection on click, set `selectOnClickRow` to `true`. The default is `false`. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ### Hide Checkbox To hide the checkbox, set `withCheckbox` to `false`. The default is `true`. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ### Disable Row To disable a row, set `enableRowSelection` to a function that returns a boolean. ```tsx const data = useMemo(() => createData(), []) return (
row.id !== "1"} withScrollArea /> ) ``` ### Control Row Selection ```tsx const [rowSelection, setRowSelection] = useState({}) const data = useMemo(() => createData(), []) return (
) ``` ### Use Filter To use a filter, set the component that controls the filter to `header` or `footer`. ```tsx const data = useMemo(() => createData(), []) return (
{ const value = (table.getColumn("email")?.getFilterValue() as string | undefined) ?? "" return ( table.getColumn("email")?.setFilterValue(ev.target.value) } /> ) }} withScrollArea /> ) ``` ### Set Default Filter To set the default filter, set `defaultColumnFilters` to an array of objects with the `id` and value of the column to filter. ```tsx const data = useMemo(() => createData(), []) return (
{ const value = (table.getColumn("email")?.getFilterValue() as string | undefined) ?? "" return ( table.getColumn("email")?.setFilterValue(ev.target.value) } /> ) }} withScrollArea /> ) ``` ### Control Filter ```tsx const [columnFilters, setColumnFilters] = useState([ { id: "email", value: "" }, ]) const data = useMemo(() => createData(), []) return (
{ const value = (table.getColumn("email")?.getFilterValue() as string | undefined) ?? "" return ( table.getColumn("email")?.setFilterValue(ev.target.value) } /> ) }} withScrollArea /> ) ``` ### Enable Column Resizing To enable column resizing, set `enableColumnResizing` to `true`. The default is `false`. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ### Change Column Resizing Method By default, the column resizing timing is changed while dragging. If you want to change it when the drag is finished, set `columnResizeMode` to `"onEnd"`. ```tsx const data = useMemo(() => createData(), []) return (
) ``` ## Props | Prop | Default | Type | Description | | ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. | | `size` | - | `"lg" \| "md" \| "sm"` | The size of the component. | | `variant` | - | `"line" \| "outline"` | The variant of the component. | | `cellProps` | - | `TransformProps>` | The props for the table cell. | | `checkboxProps` | - | `CheckboxProps` | The props for the checkbox. | | `columnFilters` | - | `ColumnFiltersState` | The column filters state of the table. | | `defaultColumnFilters` | - | `ColumnFiltersState` | The default column filters state of the table. | | `defaultPagination` | - | `PaginationState` | The default pagination state of the table. | | `defaultRowSelection` | - | `RowSelectionState` | The default row selection state of the table. | | `defaultSorting` | - | `SortingState` | The default sorting state of the table. | | `enableAutoResizeTableWidth` | `false` | `boolean` | If `true`, the table width will be automatically resized to the content. | | `enableKeyboardNavigation` | `true` | `boolean` | If `true`, the keyboard navigation will be enabled. | | `enablePagination` | `false` | `boolean` | If `true`, the pagination will be enabled. | | `footer` | - | `ReactNodeOrFunction>` | The footer of the table. | | `footerGroupProps` | - | `TransformProps>` | The props for the table footer group. | | `footerProps` | - | `TransformProps>` | The props for the table footer. | | `header` | - | `ReactNodeOrFunction>` | The header of the table. | | `headerCheckboxProps` | - | `TransformProps>` | The props for the table header checkbox. | | `headerGroupProps` | - | `TransformProps>` | The props for the table header group. | | `headerProps` | - | `TransformProps>` | The props for the table header. | | `highlightOnHover` | `false` | `boolean` | If `true`, highlight the row when the table row is hovered. | | `highlightOnSelected` | `false` | `boolean` | If `true`, highlight the row when the table row is selected. | | `initialFocusableCell` | `{rowIndex: 0, colIndex: 0}` | `{ colIndex: number; rowIndex: number }` | The initial focusable cell of the table. | | `layout` | - | `"-moz-initial" \| "auto" \| "fixed" \| "inherit" \| "initial" \| "revert-layer" \| "revert" \| "unset" ...` | The CSS `table-layout` property. | | `onColumnFiltersChange` | - | `(columnFilters: ColumnFiltersState) => void` | The callback invoked when the column filters state changes. | | `onPaginationChange` | - | `(pagination: PaginationState) => void` | The callback invoked when the pagination state changes. | | `onRowClick` | - | `(row: Row) => void` | The callback invoked when the row is clicked. | | `onRowDoubleClick` | - | `(row: Row) => void` | The callback invoked when the row is double clicked. | | `onSortingChange` | - | `(sorting: SortingState) => void` | The callback invoked when the sorting state changes. | | `pagination` | - | `PaginationState` | The pagination state of the table. | | `resizableTriggerProps` | - | `TransformProps, Header>` | The props for the resizable trigger. | | `rowCheckboxProps` | - | `TransformProps>` | The props for the table row checkbox. | | `rowProps` | - | `TransformProps>` | The props for the table row. | | `rowSelection` | - | `RowSelectionState` | The row selection state of the table. | | `scrollAreaProps` | - | `NativeTableAreaProps` | The props for the scroll area. | | `selectOnClickRow` | `false` | `boolean` | If `true`, the row will be selected when the row is clicked. | | `sorting` | - | `SortingState` | The sorting state of the table. | | `sortingIcon` | - | `ReactNodeOrFunction` | The sorting icon of the table. | | `sortingIconProps` | - | `TransformProps, Header>` | The props for the sorting icon. | | `stickyFooter` | `false` | `boolean` | If `true`, display the sticky footer. | | `stickyHeader` | `false` | `boolean` | If `true`, display the sticky header. | | `striped` | `false` | `boolean` | If `true`, display striped rows. | | `tableProps` | - | `NativeTable.RootProps` | The props for the table. | | `tbodyProps` | - | `NativeTable.TbodyProps` | The props for the table tbody. | | `tfootProps` | - | `NativeTable.TfootProps` | The props for the table tfoot. | | `theadProps` | - | `NativeTable.TheadProps` | The props for the table thead. | | `withBorder` | `false` | `boolean` | If `true`, display the outer border of the table. | | `withCheckbox` | `true` | `boolean` | If `true`, the table will have a checkbox column. | | `withColumnBorders` | `false` | `boolean` | If `true`, display line on the columns of the table. | | `withFooterCheckbox` | `false` | `boolean` | If `true`, the table will have a checkbox in the footer. | | `withFooterGroups` | `false` | `boolean` | If `true`, the table will have footer groups. | | `withScrollArea` | `false` | `boolean` | Whether to enable the scroll area. | ## Accessibility Currently, this section is being updated due to the migration of v2.