DataTable

Basic Example

Pass just dataand columns are auto-inferred from the first row's keys. Numbers are right-aligned and formatted automatically.

<DataTable
  data={[
    { name: "Acme Corp", revenue: 142300, growth: 12.5 },
    { name: "Globex Inc", revenue: 98700, growth: -3.2 },
    { name: "Initech", revenue: 67400, growth: 8.1 },
  ]}
/>

Column Types

The type property on a column definition controls formatting, alignment, and rendering automatically. This is the most powerful feature of DataTable — set a type and the component handles everything else: currency columns get locale-aware formatting, badge columns auto-map status strings to semantic colors, sparkline columns render inline charts, and progress columns show bars. Numeric types (number, currency, percent, bar) use a monospace font for easy scanning; text columns use the body font.

const columns: ColumnDef<ProductRow>[] = [
  { key: "product", header: "Product", type: "text", sortable: true, pin: "left" },
  { key: "price", header: "Price", type: "currency", sortable: true },
  { key: "growth", header: "Growth", type: "percent", sortable: true },
  { key: "status", header: "Status", type: "badge", sortable: true },
  { key: "trend", header: "Trend (7d)", type: "sparkline" },
  { key: "progress", header: "Adoption", type: "progress" },
  { key: "category", header: "Category", type: "text" },
];

<DataTable
  data={productData}
  columns={columns}
  title="Product Overview"
  striped
/>

Badge columns automatically map common status strings like "active", "pending", "failed" to semantic colors. For custom mappings, use the badgeVariant or badgeColor column properties. Status columns work with statusRules for rule-based indicator rendering. Link columns use linkHref to generate URLs dynamically.

Sorting & Multi-Sort

Columns with sortable: true cycle through ascending, descending, and none on click. Enable multiSort to allow Shift+click on additional columns for multi-level sorting (up to 3 levels). Active sort columns show numbered priority badges on their headers so users can see the sort hierarchy at a glance.

<DataTable
  data={salesReps}
  columns={[
    { key: "name", header: "Rep", type: "text", sortable: true },
    { key: "department", header: "Segment", type: "text", sortable: true },
    { key: "revenue", header: "Revenue", type: "currency", sortable: true },
    { key: "deals", header: "Deals", type: "number", sortable: true },
  ]}
  title="Sales Leaderboard"
  subtitle="Shift+click headers to multi-sort"
  multiSort
/>

// Single sort (default) — click toggles asc → desc → none
<DataTable columns={[{ key: "name", sortable: true }]} ... />

// Multi-sort — Shift+click adds secondary/tertiary sort
<DataTable columns={columns} multiSort />
// Up to 3 sort levels. Priority badges (1, 2, 3) appear on headers.

Expandable Rows

Pass a renderExpanded function to enable row expansion. Each row gets a chevron toggle on the left that reveals a detail panel below. The function receives the row data and index, and can return any React content.

<DataTable
  data={orders}
  columns={orderColumns}
  title="Recent Orders"
  renderExpanded={(row) => (
    <div className="space-y-2 text-sm text-[var(--muted)]">
      <p><strong>Order:</strong> {row.id}</p>
      <p><strong>Date:</strong> {row.date}</p>
      <p><strong>Items:</strong> {row.items} line items</p>
      <p><strong>Notes:</strong> Click any row to see its details.</p>
    </div>
  )}
/>

Conditional Formatting

Apply color rules at the column level with conditions — the same system used by KpiCard. Rules are evaluated top-to-bottom; first match wins. Supports above, below, between, equals, and compound and/or rules. For row-level highlighting, use rowConditions to apply CSS classes to entire rows based on a predicate function.

const columns = [
  { key: "metric", header: "Metric", type: "text" },
  {
    key: "value",
    header: "Current",
    type: "number",
    conditions: [
      { when: "above", value: 99, color: "emerald" },
      { when: "between", min: 50, max: 99, color: "amber" },
      { when: "below", value: 50, color: "red" },
    ],
  },
  { key: "target", header: "Target", type: "number" },
  {
    key: "delta",
    header: "Delta",
    type: "number",
    conditions: [
      { when: "above", value: 0, color: "emerald" },
      { when: "below", value: 0, color: "red" },
    ],
  },
];

<DataTable data={metrics} columns={columns} title="SLA Dashboard" />

// Row-level conditions — apply a className to entire rows
<DataTable
  data={data}
  columns={columns}
  rowConditions={[
    {
      when: (row) => row.status === "critical",
      className: "bg-red-500/10",
    },
    {
      when: (row) => row.status === "warning",
      className: "bg-amber-500/10",
    },
  ]}
/>

Pagination & Footer

Set pageSize to enable pagination with Previous/Next controls and a row range indicator. Use footer to add a summary/totals row — pass an object keyed by column key with ReactNode values. Combine with searchable for client-side filtering.

<DataTable
  data={productData}
  columns={[
    { key: "product", header: "Product", type: "text", pin: "left" },
    { key: "price", header: "Price", type: "currency" },
    { key: "growth", header: "Growth", type: "percent" },
    { key: "category", header: "Category", type: "text" },
  ]}
  title="Product Catalog"
  pageSize={3}
  searchable
  footer={{ product: "Total", price: "$19,798", growth: "", category: "" }}
/>

Data States

DataTable handles loading, empty, and error states out of the box. The loading state renders animated skeleton rows that match your column layout.

// Loading — renders skeleton rows
<DataTable data={[]} loading />

// Empty state with custom message
<DataTable data={[]} empty={{ message: "No results found" }} />

// Error state
<DataTable data={[]} error={{ message: "Failed to load data" }} />

// Stale data indicator
<DataTable data={staleData} stale={{ message: "Data is 5 minutes old" }} />

Props

Data Shape

type ColumnType = "text" | "number" | "currency" | "percent" | "link" | "badge" | "sparkline" | "status" | "progress" | "date" | "bar";

interface Column<T> {
  key: string;                   // Property key on the data object
  header?: string;               // Column header text (preferred)
  label?: string;                // @deprecated — use header
  type?: ColumnType;             // Column type — auto-formats and auto-aligns. See ColumnType docs.
  format?: FormatOption;         // Auto-format numeric values (overrides type-inferred format)
  align?: "left" | "center" | "right";  // Default: left for text, right for numbers, center for sparkline/progress
  width?: string | number;       // Column width (CSS value)
  sortable?: boolean;            // Enable sorting
  render?: (value: any, row: T, index: number) => React.ReactNode;  // Custom cell renderer
  pin?: "left";                  // Sticky column on horizontal scroll
  wrap?: boolean;                // Allow text wrapping in cells (default: truncate)
  conditions?: Condition[];      // Conditional cell coloring based on value
  linkHref?: (value: any, row: T) => string;     // URL resolver for type:"link" columns
  linkTarget?: string;           // Link target attribute (e.g. "_blank")
  badgeColor?: (value: any, row: T) => string | undefined;    // Custom badge color for type:"badge"
  badgeVariant?: (value: any, row: T) => BadgeVariant | undefined;  // Custom badge variant for type:"badge"
  statusRules?: StatusRule[];    // Threshold rules for type:"status" columns
  statusSize?: StatusSize;       // Display size for type:"status" columns
  dateFormat?: Intl.DateTimeFormatOptions;  // Intl format options for type:"date" columns
}

interface RowCondition<T> {
  when: (row: T, index: number) => boolean;  // Predicate — return true to apply className
  className: string;                          // CSS class to apply to matching rows
}

interface FooterRow {
  [key: string]: React.ReactNode;
}

Notes

• Generic component — TypeScript infers T from the data prop.
• When columns are omitted, they are auto-inferred from the first row's keys with camelCase-to-Title-Case conversion.
• Sort cycles through: asc -> desc -> none. With multiSort, Shift+click adds secondary/tertiary sorts.
• Column `header` is preferred over `label` (which is deprecated).
• Auto-alignment: numeric types (number, currency, percent, bar) right-align. sparkline/progress center-align. Everything else left-aligns.
• Column types auto-render: 'currency'/'percent'/'number' auto-format values, 'badge' renders a Badge, 'status' renders StatusIndicator, 'sparkline' renders a Sparkline, 'link' renders a clickable link, 'progress' renders a ProgressBar, 'date' formats via Intl.DateTimeFormat, 'bar' renders inline bar chart.
• The pagination component shows 'Previous' / 'Next' buttons with row range indicator.
• Search filters across all column values using case-insensitive string matching.
• renderExpanded adds a chevron toggle column. Clicking a row expands/collapses the detail panel.
• rowConditions apply CSS classes to rows matching predicates — useful for highlighting warnings or critical rows.
• crossFilter prop emits a selection signal on row click — it does NOT change the table's appearance. The dev reads the selection via useCrossFilter() and filters their own data.
• drillDown={true} auto-generates a summary KPI row + detail view from the clicked row. Pass a render function for custom panel content. Requires DrillDown.Root wrapper.
• When both drillDown and crossFilter are set on the same component, drillDown wins.

Playground

Experiment with every prop interactively. Adjust the controls on the right to see the component update in real time.

<DataTable
  data={topProducts}
  columns={[
    { key: "product", header: "Product", sortable: true, pin: "left" },
    { key: "revenue", header: "Revenue", sortable: true, format: "currency" },
    { key: "units", header: "Units Sold", sortable: true, format: "number" },
    { key: "growth", header: "Growth", sortable: true, align: "right", render: (v, row) => <...> },
    { key: "status", header: "Status", render: (v, row) => <...> },
  ]}
  title="Top Products"
  subtitle="By revenue this quarter"
/>

Related Components