gamut-datatable

Use this skill when building a DataTable for bulk data analysis, comparison, sorting, or filtering — including column configuration, the useLocalQuery hook, row action menus, empty/loading states, and

SKILL.md

GitHub

Gamut DataTable

Structured, query-capable table for bulk data analysis and comparison. Sorting, filtering, loading, and empty states are built in. Use when the goal is to scan and compare information across rows — not to manage individual items.

Source: @codecademy/gamut — packages/gamut/src/DataList/DataTable.tsx

See also: gamut-datalist — item-focused list with expansion and selection. gamut-list — lower-level list primitives for fully custom layouts. gamut-accessibility — ARIA and keyboard interaction. gamut-color-mode — dark/light mode with Background. gamut-z-index — why the row-menu-opens-Modal pattern below needs inline to work.

Storybook: Organisms / Lists & Tables / DataTable

Components

import { DataTable } from '@codecademy/gamut';
import { useLocalQuery } from '@codecademy/gamut';
Symbol Role
DataTable Root component; always renders as a table-variant List with scrolling enabled
useLocalQuery Client-side hook for sort/filter state; spread its return value directly into DataTable

When to use DataTable

  • Displaying data that users need to compare across rows (metrics, scores, statuses, dates).
  • When the data set needs sorting, filtering, or both and that logic lives client-side.
  • Dashboards, admin tables, reports, and data-dense views.
  • When rows are not individually selectable or expandable — use DataList if you need those.

Do not use DataTable when:

  • Users engage with items individually (expand for details, select for bulk actions) → use DataList.
  • The list is small, static, and needs fully custom row layouts → use List directly.
  • There is no data at all and you just need a layout container.

Design principles

  • Prioritize comparison: arrange columns to encourage scanning and finding patterns, not storytelling.
  • Surface secondary info on drill-down: use Coachmarks, Tooltips, Modals, or Flyovers rather than cramming detail into table cells.
  • Avoid information overload: determine what belongs en-masse vs. what should live on a detail surface. Order columns by priority; collapse lower-priority columns at smaller sizes.
  • Use cell-level interactions carefully: anchors and links for navigation; popovers for in-context actions.

Props

Prop Type Default Notes
id string required Unique ID for the table
idKey keyof Row required Row identifier — must be a string | number field
rows Row[] required Data array
columns ColumnConfig<Row>[] required Column definitions
query Query<Row> — Current sort/filter state; use useLocalQuery or manage externally
onQueryChange OnQueryChange<Row> — Called when sort or filter changes
loading boolean false Replaces row content with shimmer placeholders
spacing 'condensed' | 'normal' 'condensed' Row padding
scrollable boolean true Enables horizontal scroll with sticky first column
shadow boolean false Shows a right-side scroll-indicator shadow
height string '100%' Container height when scrollable is true
minHeight number 0 Minimum container height
emptyMessage ReactNode default empty state Rendered when rows is empty
showOverflow boolean — Shows overflow indicators in cells
disableContainerQuery boolean false Falls back to media queries instead of container queries
scrollToTopOnUpdate boolean false Scrolls to top when rows change
wrapperWidth string — Custom wrapper width override

ColumnConfig

Field Type Notes
key keyof Row Required; maps to a row data field
header string Column header label
type 'content' | 'header' | 'control' | 'select' | 'expand' | 'expandControl' | 'orderedHeader' | 'tableControl' ListColProps['type']; 'content' is default — see Column type
size 'content' | 'sm' | 'md' | 'lg' | 'xl' 'content' (default) fits cell contents; use sm–xl for fixed column widths
fill boolean Expands the column to fill remaining width
justify 'left' | 'right' Cell alignment
sortable boolean Adds a sort toggle to the column header
filters string[] Adds a filter dropdown with these string values
options Array<string | { text: string; value: string }> Alternative to filters when display text differs from value
render (row: Row) => ReactElement | null Custom cell renderer

Column type

type Use for
content Default; secondary data columns
header Primary label column; sticky when the table is scrollable
control Action controls (buttons, menus); right-aligned, reduced padding
select Checkbox column — DataList adds this when selectable is set
expand Expanded content area
expandControl Expand toggle column — DataList adds this when expandable is set
orderedHeader Internal; applied by ListCol for ordered lists — do not set manually
tableControl Internal; applied by table rows for type: 'control' — do not set manually

DataTable columns typically use header (sticky identifier) and control (row actions). Other values are inherited from ListCol for API parity; selection and expansion columns are handled by DataList, not ColumnConfig.

Basic usage

import { DataTable, useLocalQuery } from '@codecademy/gamut';

const columns = [
  { key: 'name', header: 'Name', size: 'md', sortable: true },
  {
    key: 'role',
    header: 'Role',
    size: 'md',
    filters: ['Engineer', 'Design', 'Product'],
  },
  {
    key: 'score',
    header: 'Score',
    size: 'sm',
    sortable: true,
    justify: 'right',
  },
];

const MyTable = ({ data }) => {
  const queryData = useLocalQuery({ idKey: 'id', rows: data, columns });

  return (
    <DataTable id="my-table" idKey="id" columns={columns} {...queryData} />
  );
};

Custom cell render

Use render for cells that need non-text content (status badges, progress bars, action buttons).

const columns = [
  { key: 'name', header: 'Name', size: 'md', type: 'header' },
  {
    key: 'status',
    header: 'Status',
    size: 'sm',
    render: (row) => (
      <Badge variant={row.status === 'active' ? 'green' : 'red'}>
        {row.status}
      </Badge>
    ),
  },
];

Row action menus

Use a type: 'control' column with PopoverContainer and Menu for row-level actions.

import {
  DataTable,
  IconButton,
  Menu,
  MenuItem,
  Modal,
  PopoverContainer,
} from '@codecademy/gamut';
import { MiniKebabMenuIcon } from '@codecademy/gamut-icons';
import { useRef, useState } from 'react';

const RowActions = ({ rowId }) => {
  const [isOpen, setIsOpen] = useState(false);
  const [isModalOpen, setIsModalOpen] = useState(false);
  const ref = useRef(null);

  return (
    <Box display="inline-block" p={8} ref={ref}>
      <IconButton
        icon={MiniKebabMenuIcon}
        tip="Row actions"
        variant="secondary"
        onClick={() => setIsOpen(!isOpen)}
      />
      <PopoverContainer
        alignment="bottom-left"
        allowPageInteraction
        closeOnViewportExit
        isOpen={isOpen}
        offset={0}
        targetRef={ref}
        onRequestClose={() => setIsOpen(false)}
      >
        <Menu borderRadius="md" spacing="normal" variant="popover">
          <MenuItem onClick={() => setIsOpen(false)}>Edit</MenuItem>
          <MenuItem
            onClick={() => {
              setIsOpen(false);
              setIsModalOpen(true);
            }}
          >
            View details
          </MenuItem>
        </Menu>
      </PopoverContainer>
      <Modal
        isOpen={isModalOpen}
        size="small"
        title="Details"
        onRequestClose={() => setIsModalOpen(false)}
      >
        {/* detail content */}
      </Modal>
    </Box>
  );
};

const columns = [
  { key: 'name', header: 'Name', size: 'md', type: 'header' },
  {
    key: 'id',
    header: '',
    size: 'sm',
    type: 'control',
    justify: 'right',
    render: (row) => <RowActions rowId={row.id} />,
  },
];

Key points:

  • closeOnViewportExit on PopoverContainer closes the menu when its row scrolls out of view.
  • allowPageInteraction lets users interact with the table while the menu is open.
  • Modals opened from menu items render at zIndex={3} by default, above the table header — this only holds because the row menu's PopoverContainer stays inline; see gamut-z-index for why a portalling menu would break this.

Scrollable table

scrollable defaults to true on DataTable. The first type: 'header' column sticks to the left. Add shadow for a visual overflow indicator.

<DataTable id="wide-table" idKey="id" columns={columns} rows={rows} shadow />

Empty state

DataTable shows a default empty state when rows is empty. Override with emptyMessage. For the tbody > tr > th layout pattern required for valid table semantics, see gamut-datalist — Empty state.

Loading state

Pass loading to replace row content with shimmer placeholders while data fetches.

<DataTable id="my-table" idKey="id" columns={columns} rows={[]} loading />

Color mode

DataTable inherits background color from the current-background token. Wrap in Background from @codecademy/gamut-styles to apply a surface color and automatically switch to dark mode contrast.

import { Background } from '@codecademy/gamut-styles';

<Background bg="black" p={8}>
  <DataTable id="dark-table" idKey="id" rows={data} columns={columns} />
</Background>;

Container queries

DataTable uses CSS container queries by default for responsive column stacking. Pass disableContainerQuery when the table lives in a constrained container or you are managing your own responsive logic — same pattern as gamut-datalist.

Accessibility

  • DataTable renders as a semantic <table> element automatically.
  • Sort controls receive aria-sort automatically when sortable is set on a column.
  • Filter controls are keyboard-accessible via the column header dropdowns.
  • For custom emptyMessage, use tbody > tr > th structure for valid table semantics (see empty state example above).