)
}
```
## Overview [#overview]
Use Data Grid when the dataset is a main part of the application. It handles advanced filters, page-scoped selection, resizable and reorderable columns, pinned columns, editable cells, server-managed state, and virtualized rows.
Data Grid does not try to copy a spreadsheet. It keeps the native table structure and HonestUI's quiet row styling, then adds controls when someone asks for them. The default view is still a toolbar, column names, rows, and a footer.
Use [Table](/docs/components/table) for static rows and columns. Use [Data Table](/docs/product/data-table) for search, simple filters, sorting, selection, and pagination on a smaller record set. Choose Data Grid when people need to customize the columns or work through thousands of records.
## Anatomy [#anatomy]
The default `DataGrid` composes those parts from feature props. It also exports each part and attaches them to `DataGrid`, so `DataGrid.Toolbar`, `DataGrid.Viewport`, and `DataGrid.Pagination` can be rearranged without replacing the state model.
Columns use TanStack Table definitions plus Data Grid options such as `filter`, `type`, `align`, `editable`, and `hideBelow`. Cell renderers can use any React content. Avatar, Badge, Menu, and Progress remain application choices rather than grid-specific APIs.
## Behavior [#behavior]
Sorting cycles through ascending, descending, and unsorted. Hold Shift while choosing another header to build a multi-column sort. The small number beside a sorted header reports its priority.
The filter builder chooses its input from the column's filter type. Applied filters stay visible in the toolbar and return pagination to the first page. Inline header filters are optional because they add weight to every column.
The header checkbox selects eligible rows on the current page. It never claims to select records that the browser has not loaded. Pass a row predicate to `selection` when only some rows can be selected.
Column headers support pointer reordering. The same menu includes Move left and Move right, so dragging is not the only path. Resize handles accept a pointer, double-click to reset, and Left or Right Arrow in 8px steps. Pinned columns stay inside the scrolling frame.
## Accessibility [#accessibility]
Pass `caption` to name the table. Data Grid renders a native `
` with column headers and body rows. Sort direction uses `aria-sort`. Selection checkboxes expose checked and indeterminate state through HonestUI Checkbox.
When virtualization is enabled, the table exposes the complete row count and each rendered row's position with `aria-rowcount` and `aria-rowindex`. These values include header rows. Pass `rowCount` when the server knows about rows that are not loaded in the browser.
Use `getRowLabel` to name each row checkbox with the record itself, such as "Select Sarah Chen." The built-in fallback uses a row number, which is less useful when rows move after sorting.
When a row cannot be selected, return a short explanation from `getRowSelectionDisabledReason`. The grid adds it to the disabled checkbox name, so the reason is available without relying on a tooltip.
Set `keyboardNavigation` when people need cell movement. Arrow keys move between cells. Home and End move across a row. Ctrl+Home and Ctrl+End move to the first or last grid cell. Enter starts editing or moves into an interactive control. Tab saves an edit and moves to the next cell. Shift+Tab saves and moves to the previous cell. Space toggles row selection. Inputs, selects, menus, and other controls keep their own keyboard behavior.
Wide grids scroll inside `DataGridViewport`. This is a valid two-dimensional data region, but the toolbar and surrounding page must still reflow at zoom. Test the finished grid with keyboard input, 200% and 400% zoom, a supported screen reader, forced colors, and long translated values.
## Installation [#installation]
Install the behavior and virtualization packages.
```bash
npm install @tanstack/react-table @tanstack/react-virtual
```
Copy the Data Grid files into your project.
Update the import paths to match your project.
## Usage [#usage]
Start with columns and rows, then enable the controls the task needs.
```tsx
import {
DataGrid,
type DataGridColumn,
} from "@/components/ui/data-grid/data-grid"
const columns: DataGridColumn[] = [
{
accessorKey: "name",
header: "Name",
size: 220,
minSize: 160,
filter: { type: "text" },
},
{
accessorKey: "status",
header: "Status",
filter: {
type: "enum",
options: ["Active", "Pending", "Inactive"],
},
},
{
accessorKey: "revenue",
header: "Revenue",
type: "currency",
align: "right",
},
]
```
### Compose the shell [#compose-the-shell]
Pass children when the default order does not fit the page. The same table instance is available to every part through context.
```tsx
{bulkActions}
```
### Control server state [#control-server-state]
For server data, pass the rows from the current response, the total row count, controlled state, and matching callbacks. Set each `manual*` prop for work the server owns.
```tsx
```
The grid reports intent. Your application owns the request, cancellation, stale response handling, and error message. Data Grid does not require a fetching library.
## Do not do this [#do-not-do-this]
Do not sort only the loaded server page. Ten rows may appear sorted while the other 9,990 records stay in the wrong order.
Do not place a visible control in the toolbar unless it works. Pass `toolbar.refresh` only when there is a refresh callback. The built-in CSV action exports the filtered rows available to the table and treats formula-prefixed string values as text. For a complete server export, pass `toolbar.export.onExport`, let the server build the file, and apply equivalent spreadsheet-injection protection there.
Do not replace wide rows with cards on a narrow screen. Keep the column relationships and contain horizontal scrolling inside the viewport. Hide a lower-priority column with `hideBelow` only when the application can remove that information safely.
## Examples [#examples]
### Filters [#filters]
The filter builder and inline header filters use text, enum, number, currency, date, and boolean column types. Active filters remain above the rows.
```tsx
"use client"
import { DataGrid } from "@/registry/default/product/data-grid/data-grid"
import {
getGridUserColumns,
gridUsers,
} from "@/components/data-grid-example-data"
const columns = getGridUserColumns()
export function DataGridFilters() {
return (
)
}
```
### Column controls [#column-controls]
Resize a column from its right edge. Drag a header to reorder it, use the menu as a keyboard alternative, or pin a column while the viewport scrolls.
```tsx
"use client"
import { DataGrid } from "@/registry/default/product/data-grid/data-grid"
import {
getGridUserColumns,
gridUsers,
} from "@/components/data-grid-example-data"
const columns = getGridUserColumns()
export function DataGridColumns() {
return (