---
name: data-table
description: "Build accessible data tables as companions or alternatives to D3.js visualizations. Use this skill when the user needs a table alternative to a chart, sortable/filterable data tables, chart↔table toggle, linked highlighting between table rows and chart elements, virtual scrolling for large datasets, column management, keyboard navigation, conditional formatting, grouping/subtotals, CSV export, or any pattern where tabular data complements or replaces a visualization."
---
# Data Tables for D3 Visualizations
Charts show patterns; tables show values. When the viewer's task is looking up a specific number, comparing exact figures across rows, or exporting data, a table outperforms any chart. Build tables as first-class views alongside D3 visualizations, not as accessibility afterthoughts.
Related: `linked-views` · `brushing` · `canvas-accessibility` · `color` · `responsive` · `sparkcharts`
## Table vs. Chart: When the Table Wins
Use a table — not a chart — when:
- **Exact value lookup** — the viewer needs specific numbers, not trends. Charts encode values as position/length at ~10% precision; tables give the exact figure.
- **Small n** — fewer than ~20 data points with 3+ attributes. A chart of 8 rows wastes space.
- **Mixed units** — dollars, percentages, counts, and dates side-by-side. No single y-axis handles that.
- **Comparison across attributes** — the viewer reads across a row. Charts require multiple encodings or facets.
- **Mobile** — complex charts degrade on small screens; tables scroll naturally.
Offer **both views** (toggle or side-by-side) when different viewers need different tasks.
## When Not to Use This
Don't build a table when the viewer needs **distribution shape**, **trends over time**, or **spatial patterns**. A 500-row table of time-series data is less useful than a line chart. If the task is "which is biggest?", a bar chart communicates faster than scanning a column.
## Number Formatting and Alignment
Poor alignment is the most common table design failure.
```css
td.num { text-align: right; font-variant-numeric: tabular-nums; }
th.num { text-align: right; }
```
- **Consistent precision** — all values in a column get the same decimal places. `d3.format(',.1f')` not a mix of `3.1` and `3.14159`.
- **Units in the header, not every cell** — write `GDP ($M)` in `
`, format cells as `1,234`. Exception: currency symbols aid scanning in financial tables.
- **Group separators** — `d3.format(',')` turns `1234567` into `1,234,567`.
## Architecture: Chart ↔ Table Toggle
```
┌──────────────────────────────────┐
│ Toggle bar (chart / table) │
├──────────────────────────────────┤
│ Chart container OR Table view │
│ (canvas/SVG) (sticky │
│ header + │
│ scroll │
│ body) │
├──────────────────────────────────┤
│ Status bar (count, filter info) │
└──────────────────────────────────┘
```
Table and chart are sibling containers. Toggle hides one and shows the other via `display`/`aria-hidden`. Both bind the same data array so filter/selection state is shared. Use `aria-pressed` on the toggle button.
## Column Specification
```js
const columns = [
{ key: 'name', label: 'Name', type: 'string' },
{ key: 'population', label: 'Population', type: 'number', format: d3.format(',') },
{ key: 'gdp', label: 'GDP per Capita', type: 'number', format: d3.format('$,.0f') },
{ key: 'continent', label: 'Continent', type: 'string' }
];
```
`type` drives sort comparator (lexicographic vs. numeric) and cell alignment (right for numbers).
## D3 Nested Join Pattern
Two-level join — rows keyed by `d.id`, cells by column index:
```js
const rows = d3.select(tbody).selectAll('tr')
.data(data, d => d.id)
.join('tr');
rows.selectAll('td')
.data(d => columns.map(col => col.format ? col.format(d[col.key]) : d[col.key]))
.join('td')
.text(d => d);
```
The **outer join uses a key function** (`d => d.id`) for stable DOM identity during filter/sort — without it, D3 reuses `
` by index, causing flash-of-wrong-content. The **inner cell join must NOT have a key function** — cells map 1:1 to columns by index. A key causes collisions when two cells format to the same string.
## Sortable Columns
Click header to sort ascending, click again for descending:
- Use `d3.ascending`/`d3.descending` as comparators
- Set `aria-sort` on the active `
` (`"ascending"`, `"descending"`, `"none"` on others)
- Make headers `tabindex="0"`, handle Enter/Space for keyboard users
- **Sort a copy**: `[...data].sort(...)`. `Array.sort()` mutates in place — if the chart reads the same array, its order silently changes.
### Multi-Sort
Shift-click adds secondary sort keys. Track as an ordered array `[{key, dir}]`:
```js
let sortKeys = []; // first entry is primary
function onHeaderClick(col, event) {
if (event.shiftKey) {
const idx = sortKeys.findIndex(s => s.key === col.key);
if (idx >= 0) sortKeys[idx].dir *= -1;
else sortKeys.push({ key: col.key, dir: 1 });
} else {
const prev = sortKeys.find(s => s.key === col.key);
sortKeys = [{ key: col.key, dir: prev ? prev.dir * -1 : 1 }];
}
renderTable(applyFilters(data));
}
// Chain comparators — fall through when equal
const multiSort = keys => (a, b) => {
for (const { key, dir } of keys) {
const cmp = d3.ascending(a[key], b[key]);
if (cmp !== 0) return cmp * dir;
}
return 0;
};
```
Show sort priority with a small numeral badge (1, 2, 3) next to the arrow. Set `aria-sort` only on the primary column.
## Linked Highlighting
Hover/select in chart highlights the table row, and vice versa. See `linked-views` skill for the shared state pattern (`d3.dispatch` or a state object with `hoveredId`/`selectedIds`/`notify()`).
Table-specific details:
- `.classed('hovered', d => d.id === state.hoveredId)` on `
` elements
- **Scroll-to-row**: `row.scrollIntoView({ block: 'nearest' })` on selection only — on hover it fights the user's scrolling
## Filtering
Chain independent filters through a pipeline. Each filter is a predicate; a row passes only if every predicate returns true:
```js
const activeFilters = new Map(); // key → predicate fn
function applyFilters(data) {
const preds = [...activeFilters.values()];
const filtered = preds.length ? data.filter(d => preds.every(f => f(d))) : data;
liveRegion.textContent = `Showing ${filtered.length} of ${data.length} rows`;
return filtered;
}
```
`liveRegion` is a `div[aria-live="polite"]` — without it, screen reader users filter blindly.
### Global text search
Debounce input, search across all columns:
```js
const searchInput = d3.select('#search').on('input', debounce(e => {
const q = e.target.value.toLowerCase();
if (q) activeFilters.set('search', d =>
columns.some(col => String(d[col.key]).toLowerCase().includes(q)));
else activeFilters.delete('search');
renderTable(applyFilters(data));
}, 150));
function debounce(fn, ms) {
let t; return (...a) => { clearTimeout(t); t = setTimeout(() => fn(...a), ms); };
}
```
### Other filter types
**Categorical dropdown**: build `