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

Registros operacionais

Comece com chaves estáveis de coluna e valores id nas linhas. hover dá uma pista para percorrer as linhas, mantendo os dados do registro em células de tabela reais.

Project	Owner	Status
Atlas	Maya Chen	Healthy
Orbit	Jon Bell	At risk
Nova	Priya Shah	Planning

Ordenação e seleção de linhas

Marque como sortable apenas os campos com uma ordem útil e forneça labels.selectRow como função quando cada checkbox precisar anunciar a pessoa ou o registro que seleciona.


Maya Chen	Design	4
Jon Bell	Engineering	12
Priya Shah	Operations	7

Linhas em carregamento

Passe um número para loading quando o resultado esperado tiver uma densidade conhecida. Isso mantém a forma da tabela enquanto os registros carregam, em vez de trocar a região de dados por um spinner.

	Project	Owner	Updated

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.
Quando onRowClick está presente, o estilo de hover é ligado automaticamente, mas a linha ainda não é um controle operável pelo teclado. Coloque um botão ou link real em uma célula para uma ação pelo teclado.

API e código

Nome	Tipo	Obrigatória	Descrição
`columns`	`DataTableColumn[]`	Obrigatória	Columns rendered in the supplied order.
`rows`	`RowShape[]`	Obrigatória	Row records whose values may be any renderable React node. An `id` value is used for keys and selection.
`sorting`	`DataTableSorting \| null`	—	Controlled sorting state. Pass `null` for unsorted rows.
`defaultSorting`	`DataTableSorting \| null`	—	Initial sorting state when uncontrolled. Default: `null`.
`onSortChange`	`(sorting: DataTableSorting \| null) => void`	—	Called after sorting changes.
`selectable`	`boolean`	—	Whether to render row and select-all checkboxes.
`selected`	`Array<string \| number>`	—	Controlled selected row identifiers.
`defaultSelected`	`Array<string \| number>`	—	Initial selected row identifiers when uncontrolled.
`onSelectionChange`	`(selected: Array<string \| number>) => void`	—	Called after the selected row identifiers change.
`stickyHeader`	`boolean`	—	Whether the header remains visible while the table scrolls.
`maxHeight`	`number \| string`	—	Maximum height for the scrollable table area.
`density`	`'comfortable' \| 'compact'`	—	Row density. Default: `"comfortable"`.
`loading`	`boolean \| number`	—	Whether to render loading placeholders, or the number of placeholder rows.
`empty`	`ReactNode`	—	Content shown instead of the default empty-state label.
`footer`	`ReactNode`	—	Content rendered below the scrollable table area.
`hover`	`boolean`	—	Whether rows highlight on hover. Automatically enabled when `onRowClick` is supplied.
`onRowClick`	`(row: RowShape) => void`	—	Called when a data row is clicked.
`labels`	`DataTableLabels`	—	Labels for controls and the default empty state. Merged over the English defaults.

x-data="lyraDataTable({ … })"

Opção	Tipo	Obrigatória	Descrição
`sorting`	`LyraDataTableSorting \| null`	—	Controlled sort state. Modelable with `x-modelable="sorting"`. Default: `null`.
`selected`	`string[]`	—	Controlled selected served row ids. Modelable with `x-modelable="selected"`. Default: `[]`.
`clientSort`	`boolean`	—	Reorder served rows in the browser after sorting. Default: `false`.

Sem React, componha as classes da tabela — estado de ordenação e seleção, rótulos dos checkboxes e a transição de carregamento ficam com você:

html

<div class="lyra-table-wrap">
  <div class="lyra-table-scroll">
    <table class="lyra-table lyra-table--hover">
      <thead>
        <tr>
          <th class="lyra-table__check">
            <input class="lyra-checkbox" type="checkbox" aria-label="Selecionar todos" />
          </th>
          <th aria-sort="ascending">
            <button class="lyra-table__sortbtn lyra-table__sortbtn--active" type="button">
              Projeto
            </button>
          </th>
          <th>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>
          <td class="lyra-table__primary">Atlas</td>
          <td>Saudável</td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

<lyra:data-table> Gerado do lyra-ds/blade v0.10.0.

O comportamento vem de lyraDataTable() — instale @lyra-ds/alpine e veja a aba HTML + Alpine.

Prop	Padrão	Obrigatória	Valores de exemplo
`columns`	—	Obrigatória	—
`rows`	—	Obrigatória	—
`sorting`	`null`	—	—
`selectable`	`false`	—	—
`selected`	`[]`	—	—
`clientSort`	`false`	—	—
`stickyHeader`	`false`	—	—
`maxHeight`	`null`	—	—
`density`	`'comfortable'`	—	`compact`
`loading`	`false`	—	—
`empty`	`null`	—	—
`hover`	`false`	—	—
`labels`	`[]`	—	—

blade

<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
/>