DataTable

DataTable adiciona comportamento operacional a um conjunto de registros. Escolha-o quando as pessoas precisarem ordenar, selecionar ou agir sobre linhas; escolha Table quando os registros só precisarem de uma apresentação tabular simples e comparável.

Exemplos

Quando usar

Use DataTable para conjuntos operacionais de registros que as pessoas precisam ordenar, selecionar, percorrer em uma área fixa ou abrir a partir de uma linha.

Prefira outro componente quando:

• Os registros só precisam de campos alinhados para comparação — use Table, a tabela estática mais simples.
• Os registros são arquivos que alguém precisa navegar e manipular — use FileManager.
• Não há registros para mostrar após o carregamento — use EmptyState para uma ausência de página inteira, ou o conteúdo empty de DataTable quando a tabela ainda for um contexto útil.

Acessibilidade

• DataTable renderiza uma <table> real, com cabeçalhos e células. Um cabeçalho ordenável é um botão, e o cabeçalho ativo informa aria-sort como crescente ou decrescente.

• Com selectable, ela renderiza checkboxes nativos para cada linha e um checkbox de selecionar todos. O checkbox geral fica indeterminado quando apenas parte do conjunto está selecionada.

• labels.selectRow usa por padrão o nome repetido em inglês "Select row". Passe uma string ou uma função como (row) => 'Select ' + row.name para dar a cada checkbox um nome acessível traduzido e distinguível.

• O id da linha é usado como chave React e para seleção. Se uma linha não tiver id string ou numérico, seu fallback vem da posição original de entrada, então a seleção continua nessa linha depois da ordenação.

• 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.

• Dê a cada tabela um caption descritivo (use captionHidden quando ele deve aparecer apenas para tecnologias assistivas). aria-label e aria-labelledby são encaminhados à tabela.

• Marque a coluna de identificação com rowHeader: true; as células do corpo serão <th scope="row">. Os cabeçalhos de coluna usam scope="col".

• A área de rolagem é uma região focável e nomeada. O nome vem do caption, ou pode ser definido com scrollLabel. Durante o carregamento, a tabela expõe aria-busy e labels.loading fornece um anúncio oculto.

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="Projetos" 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 e código

<div class="lyra-table-wrap">
  <div class="lyra-table-scroll" role="region" tabindex="0" aria-label="Projetos">
    <table class="lyra-table lyra-table--hover">
      <caption>
        Projetos
      </caption>
      <thead>
        <tr>
          <th scope="col" class="lyra-table__check">
            <input class="lyra-checkbox" type="checkbox" aria-label="Selecionar todos" />
          </th>
          <th scope="col" aria-sort="ascending">
            <button class="lyra-table__sortbtn lyra-table__sortbtn--active" type="button">
              Projeto
            </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="Selecionar Atlas" checked />
          </td>
          <th scope="row" class="lyra-table__primary">Atlas</th>
          <td>Saudável</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
/>