DataTable

DataTable adds operational behavior to a set of records. Choose it when people need to sort, select or act on rows; choose Table when the records only need a simple, comparable tabular presentation.

Examples

When to use

Use DataTable for operational record sets that people need to sort, select, scan in a fixed area or manage with explicit actions.

Reach for something else when:

• The records only need aligned fields for comparison — use Table, the simpler static table.
• The records are files people need to browse and act on — use FileManager.
• There are no records to show after loading — use EmptyState for a full-page absence, or DataTable's empty content when the table itself remains useful context.

Accessibility

• DataTable renders a real <table> with table headings and cells. A sortable heading is a button, and the active heading reports aria-sort as ascending or descending.

• With selectable, it renders native checkboxes for each row and a select-all checkbox. The select-all checkbox becomes indeterminate when only part of the set is selected.

• labels.selectRow defaults to the repeated English name "Select row". Pass a string or a function such as (row) => 'Select ' + row.name to give every row checkbox a translated, distinguishable accessible name.

• A row's id is used for its React key and selection. If a row has no string or numeric id, its fallback comes from its original input position, so selection stays with that row after sorting.

• DataTable owns table layout, sorting, and selection. A command belongs to the React consumer in a cell: use a native button for an operation and a native link for navigation. Plain cells and rows are not commands.

• Set hover to true only when a visual scanning affordance is useful. It is not implied by a consumer action.

• Give every table a descriptive caption (use captionHidden when it should only be read by assistive technology). aria-label and aria-labelledby are forwarded to the table.

• Mark the identifying column with rowHeader: true; it renders body cells as <th scope="row">. Column headings use scope="col".

• The scroll area is a focusable, named region. Its name comes from the caption, or you can set scrollLabel. While loading, the table exposes aria-busy and labels.loading supplies a hidden status announcement.

React cell actions

Move each former row command into an explicit action cell during manual migration. The old onRowClick contract is removed under the project's pre-1.0 compatibility exception for unsafe contracts; the earliest correction is 0.6.0 before stable release, or stable 1.0.0. Keep the action's stable domain identity in the consumer, and keep selection and sorting callbacks separate. Styles and the static Alpine contract are unchanged.

import { useState } from 'react';
import { Badge, Button, DataTable, type DataTableColumn } from '@lyra-ds/react';

const columns: DataTableColumn[] = [
  { key: 'project', label: 'Project', rowHeader: true },
  { key: 'owner', label: 'Owner' },
  { key: 'status', label: 'Status' },
  { key: 'actions', label: 'Actions' },
];

const projects = [
  {
    id: 'atlas',
    project: 'Atlas',
    owner: 'Maya Chen',
    status: <Badge tone="success">Healthy</Badge>,
  },
  {
    id: 'orbit',
    project: 'Orbit',
    owner: 'Jon Bell',
    status: <Badge tone="warning">At risk</Badge>,
  },
  {
    id: 'nova',
    project: 'Nova',
    owner: 'Priya Shah',
    status: <Badge tone="neutral">Planning</Badge>,
  },
];

export function ProjectTable() {
  const [openedProject, setOpenedProject] = useState<string | null>(null);
  const rows = projects.map((project) => ({
    ...project,
    actions: (
      <Button
        type="button"
        size="sm"
        variant="secondary"
        onClick={() => setOpenedProject(project.id)}
        tabIndex={0}
      >
        Open {project.project}
      </Button>
    ),
  }));
  const opened = projects.find((project) => project.id === openedProject);

  return (
    <div>
      <DataTable caption="Projects" columns={columns} rows={rows} hover />
      <p aria-live="polite">
        {opened
          ? `Showing details for ${opened.project}. Owner: ${opened.owner}.`
          : 'Choose a project action to view its details.'}
      </p>
    </div>
  );
}

API and code

<div class="lyra-table-wrap">
  <div class="lyra-table-scroll" role="region" tabindex="0" aria-label="Projects">
    <table class="lyra-table lyra-table--hover">
      <caption>
        Projects
      </caption>
      <thead>
        <tr>
          <th scope="col" class="lyra-table__check">
            <input class="lyra-checkbox" type="checkbox" aria-label="Select all" />
          </th>
          <th scope="col" aria-sort="ascending">
            <button class="lyra-table__sortbtn lyra-table__sortbtn--active" type="button">
              Project
            </button>
          </th>
          <th scope="col">Status</th>
        </tr>
      </thead>
      <tbody>
        <tr class="lyra-table__row--selected">
          <td class="lyra-table__check">
            <input class="lyra-checkbox" type="checkbox" aria-label="Select Atlas" checked />
          </td>
          <th scope="row" class="lyra-table__primary">Atlas</th>
          <td>Healthy</td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

<lyra:data-table
    :columns="[
        ['key' => 'name', 'label' => 'Project', 'sortable' => true],
        ['key' => 'owner', 'label' => 'Owner'],
        ['key' => 'issues', 'label' => 'Open issues', 'align' => 'end'],
    ]"
    :rows="[
        ['id' => '1', 'name' => 'Website redesign', 'owner' => 'Ana Ribeiro', 'issues' => 12],
        ['id' => '2', 'name' => 'Mobile app', 'owner' => 'João Martins', 'issues' => 4],
    ]"
    density="comfortable"
    hover
/>