DataTable

{
  "description": "Data-driven table with sorting, highlighting, and cell rendering.",
  "props": {
    "columns": {
      "type": "array",
      "items": {
        "key": "string (required)",
        "label": "string (required)",
        "as": "enum [text, number, code, timestamp, badge] (default: text)",
        "highlight": "boolean (default: false)",
        "sortable": "boolean (default: inherits from table)",
        "width": "string",
        "align": "enum [left, right]",
        "render": "(value, originalRow) => ReactNode; called for mounted cells only"
      },
      "required": true,
      "description": "Column descriptors. Each item: { key: string (required), label: string (required), as?: 'text'|'number'|'code'|'timestamp'|'badge' (default 'text'), highlight?: boolean (default false), sortable?: boolean (default inherits table 'sortable'), width?: string (CSS width), align?: 'left'|'right' }. 'number'/'timestamp' cells render mono + right-aligned; with columnWidths a 'number' cell wraps only between digit groups and keeps a unit with its last group; 'badge' maps the value to a text-only Badge (success/warning/error/info use their semantic color, otherwise neutral). Use a custom render for outlined badges or an explicit indicator."
    },
    "data": {
      "type": "array",
      "required": true,
      "description": "Array of row objects (Record<string, unknown>) keyed by column.key."
    },
    "sortable": {
      "type": "boolean",
      "default": false,
      "description": "Enables column header sort buttons (cycles ascending → descending → unsorted) when sortDescriptor is omitted. Per-column 'sortable: false' opts a column out. Designed for about 150 rows without virtualization: development warns above that; use DataGrid or virtualization for larger result sets."
    },
    "sortDescriptor": {
      "type": "node",
      "description": "Read-only { key: string, direction: 'asc' | 'desc' } metadata for rows already sorted by the caller. The matching header exposes aria-sort and a direction glyph; data order is preserved and internal header sort controls are disabled even when sortable is true. Pass null for externally managed source order. Omit to retain existing internal sortable behavior."
    },
    "dense": {
      "type": "boolean",
      "default": false,
      "description": "Compact rows: 32px minimum height with 4px vertical cell padding. Default rows use a 40px minimum and 8px padding. Rows grow with content; explicit virtualization.rowHeight overrides these dimensions."
    },
    "onRowClick": {
      "type": "function",
      "description": "(row, indexInSuppliedData) => void. The index is the row's index in data, also after a header sort. Adds a native action button to the first cell while preserving table row semantics. Text and number cells become the button label; React content remains independent beside an Open row button. Nested controls and editable content do not activate the row. Enter/Space activate the row button."
    },
    "getRowId": {
      "type": "function",
      "description": "(row, index) => string. Stable React key per row; falls back to the index. Keep it pure: IDs are read again only when data changes, not when only the function does."
    },
    "caption": {
      "type": "string",
      "description": "Accessible table caption, visually hidden (sr-only). It also names the table's scroll region, '<caption> scroll viewport': a table whose columns do not fit scrolls sideways inside its own box, which is a keyboard tab stop while it scrolls; the page never widens."
    },
    "emptyMessage": {
      "type": "string",
      "default": "No results.",
      "description": "Message spanning all columns when data is empty."
    },
    "columnWidths": {
      "type": "node",
      "description": "Record<columnKey, CSS pixel width> for fixed table layout. Unspecified columns use 160 pixels. DataGrid provides bounded user controls."
    },
    "pinnedColumnKeys": {
      "type": "array",
      "description": "Column keys to keep sticky at the leading edge. Supply pinned columns first in columns, in the desired order, with columnWidths for accurate offsets. DataGrid manages this ordering automatically."
    },
    "virtualization": {
      "type": "node",
      "description": "Optional {height, rowHeight?, estimateRowHeight?, overscan?}. Native rows are windowed in a labeled scrolling region. Omit rowHeight for measured variable heights; fixed rows clip overlong content. Prefer DataGrid for its built-in paginated fallback. Stable getRowId is required for retained focus across data changes."
    },
    "rowIndexOffset": {
      "type": "number",
      "default": 0,
      "description": "Zero-based offset into the complete result set. Data rows announce offset + local index + 2, including the header."
    },
    "totalRowCount": {
      "type": "number",
      "description": "Total data rows excluding the header. Native table aria-rowcount includes the header as one additional row."
    }
  },
  "composable_with": [
    "Card"
  ],
  "never_inside": [
    "DataTable"
  ],
  "example": "<DataTable\n  columns={[\n    { key: \"service\", label: \"SERVICE\" },\n    { key: \"latency\", label: \"LATENCY\", as: \"number\", highlight: true },\n    { key: \"status\", label: \"STATUS\", as: \"badge\" }\n  ]}\n  data={rows}\n  sortable\n/>"
}