Skip to content

tables.md

Latest commit

 

History

History
206 lines (156 loc) · 6.83 KB

tables.md

File metadata and controls

206 lines (156 loc) · 6.83 KB

Tables

Data tables with built-in sorting, search, pagination, and visual column types. Tables use the TableSpec type and render through the <DataTable> component (or createTable in vanilla JS).

Quick start

import { DataTable } from "@opendata-ai/openchart-react";

const spec = {
  type: "table",
  data: [
    { city: "San Francisco", temp: 18.2, pop: 874961 },
    { city: "New York", temp: 12.8, pop: 8336817 },
    { city: "Austin", temp: 20.5, pop: 978908 },
  ],
  columns: [
    { key: "city", label: "City" },
    { key: "temp", label: "Avg Temp (C)", format: ".1f" },
    { key: "pop", label: "Population", format: ",.0f" },
  ],
  chrome: { title: "City comparison" },
  search: true,
};

<DataTable spec={spec} />

For Vue, import from @opendata-ai/openchart-vue. For Svelte, import from @opendata-ai/openchart-svelte. For vanilla JS, use createTable(container, spec) from @opendata-ai/openchart-vanilla.

Live example: Basic table

Column visual types

Each column can have one visual feature. These turn plain numbers into scannable visual patterns.

Heatmap

Color cell backgrounds based on numeric values. Good for spotting high/low values at a glance.

{
  key: "temp",
  label: "Avg Temp (C)",
  format: ".1f",
  heatmap: { palette: "redBlue" },
}
Config field Type Default Description
palette string | string[] theme sequential Palette name ('blue', 'redBlue') or array of color stops
domain [number, number] auto from data Explicit min/max for the color scale
colorByField string same column Use a different field's values for coloring

Live examples: Heatmap table | Election results

Inline bar

Proportional bars within cells. Makes relative magnitudes immediately visible.

{
  key: "pop",
  label: "Population",
  format: ",.0f",
  bar: {},
}
Config field Type Default Description
maxValue number auto from data Maximum value for the bar scale
color string first categorical color Bar fill color

Sparkline

Mini charts embedded in cells. Use for showing trends within a row.

{
  key: "trend",
  label: "6-Month Trend",
  sparkline: { type: "line", valuesField: "trend" },
}

The data for sparklines is an array stored in the row: { trend: [15, 16, 17, 18, 19, 18] }.

Config field Type Default Description
type 'line' | 'bar' | 'column' 'line' Sparkline chart type
valuesField string same column Field containing the array of values
color string first categorical color Sparkline color

Live examples: Stock sparklines | Revenue columns

Flag

Render country names or codes as flag emojis.

{
  key: "country",
  label: "Country",
  flag: true,
}

Live examples: Flags table | Country comparison

Image

Display cell values as images (URLs).

{
  key: "avatar",
  label: "Photo",
  image: { width: 32, height: 32, rounded: true },
}
Config field Type Default Description
width number 24 Image width in pixels
height number 24 Image height in pixels
rounded boolean false Circular crop

Category colors

Color-code cells by categorical value.

{
  key: "status",
  label: "Status",
  categoryColors: {
    "Active": "#2a9d8f",
    "Inactive": "#e76f51",
    "Pending": "#f4a261",
  },
}

Interactive features

All features are opt-in via top-level TableSpec properties.

Feature Config Default Description
Sorting columns[].sortable true Click column headers to sort. Set false on individual columns to disable.
Search search: true false Shows a search/filter bar above the table
Pagination pagination: { pageSize: 25 } false Paginate rows. Use true for default page size or an object to set it explicitly.
Sticky first column stickyFirstColumn: true false Freeze the first column during horizontal scroll
Compact mode compact: true false Reduced padding and font sizes for dense data
Responsive responsive: true true Table adapts to container width

Full-featured example

const spec = {
  type: "table",
  data: myData,
  columns: [
    { key: "name", label: "Company", sortable: true },
    { key: "revenue", label: "Revenue", format: "$,.0f", bar: {} },
    { key: "growth", label: "Growth", format: "+.1f%", heatmap: { palette: "redBlue" } },
    { key: "sparkline", label: "12-Month", sparkline: { type: "line", valuesField: "sparkline" } },
  ],
  chrome: { title: "Company performance" },
  search: true,
  pagination: { pageSize: 20 },
  stickyFirstColumn: true,
};

Event handling

Tables support interaction callbacks for building drill-down interfaces and controlled components.

Handler Signature When it fires
onRowClick (row: Record<string, unknown>) => void User clicks a table row
onSortChange (sort: SortState | null) => void Sort state changes
onSearchChange (query: string) => void Search query changes
onPageChange (page: number) => void Page changes
onStateChange (state: TableState) => void Any table state changes (vanilla only)

For controlled component patterns and detailed event handling, see the integration guide.

Related docs