Table
A native data table with a header rule, row dividers, hover and selection fills, sortable headers with a glyph, and static empty and loading rows.
stable · light DOM · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
default
| Atlas library | Avery Kim | Ready | 24 |
| Orion workspace | Jordan Lee | In progress | 12 |
| Field notes | Morgan Noor | Ready | 38 |
| Signal monitor | Riley Stone | Review | 6 |
| No rows match. | |||
| ⋯ Loading rows | |||
<j3w1-table id="example-table-default"><div class="table-scroller" tabindex="0" role="region" aria-label="Project records"><table class="table"><caption class="table-caption">Project records · synthetic fixture</caption><thead class="table-head"><tr><th class="table-header" scope="col"><button class="table-sort" type="button">Project<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Owner<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Status<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Scope<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th></tr></thead><tbody class="table-body"><tr class="table-row" id="example-table-default-record-0" data-status="Ready"><td class="table-cell" id="example-table-default-record-name-0">Atlas library</td><td class="table-cell">Avery Kim</td><td class="table-cell">Ready</td><td class="table-cell">24</td></tr><tr class="table-row" id="example-table-default-record-1" data-status="In progress"><td class="table-cell" id="example-table-default-record-name-1">Orion workspace</td><td class="table-cell">Jordan Lee</td><td class="table-cell">In progress</td><td class="table-cell">12</td></tr><tr class="table-row" id="example-table-default-record-2" data-status="Ready"><td class="table-cell" id="example-table-default-record-name-2">Field notes</td><td class="table-cell">Morgan Noor</td><td class="table-cell">Ready</td><td class="table-cell">38</td></tr><tr class="table-row" id="example-table-default-record-3" data-status="Review"><td class="table-cell" id="example-table-default-record-name-3">Signal monitor</td><td class="table-cell">Riley Stone</td><td class="table-cell">Review</td><td class="table-cell">6</td></tr><tr class="table-empty" hidden=""><td class="table-empty-cell" colspan="4">No rows match.</td></tr><tr class="table-loading" hidden=""><td colspan="4">⋯ Loading rows</td></tr></tbody></table></div></j3w1-table>sticky-header
| Atlas library | Avery Kim | Ready | 24 |
| Orion workspace | Jordan Lee | In progress | 12 |
| Field notes | Morgan Noor | Ready | 38 |
| Signal monitor | Riley Stone | Review | 6 |
| No rows match. | |||
| ⋯ Loading rows | |||
<j3w1-table id="example-table-sticky-header"><div class="table-scroller" tabindex="0" role="region" aria-label="Project records"><table class="table"><caption class="table-caption">Project records · synthetic fixture</caption><thead class="table-head"><tr><th class="table-header" scope="col"><button class="table-sort" type="button">Project<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Owner<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Status<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Scope<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th></tr></thead><tbody class="table-body"><tr class="table-row" id="example-table-sticky-header-record-0" data-status="Ready"><td class="table-cell" id="example-table-sticky-header-record-name-0">Atlas library</td><td class="table-cell">Avery Kim</td><td class="table-cell">Ready</td><td class="table-cell">24</td></tr><tr class="table-row" id="example-table-sticky-header-record-1" data-status="In progress"><td class="table-cell" id="example-table-sticky-header-record-name-1">Orion workspace</td><td class="table-cell">Jordan Lee</td><td class="table-cell">In progress</td><td class="table-cell">12</td></tr><tr class="table-row" id="example-table-sticky-header-record-2" data-status="Ready"><td class="table-cell" id="example-table-sticky-header-record-name-2">Field notes</td><td class="table-cell">Morgan Noor</td><td class="table-cell">Ready</td><td class="table-cell">38</td></tr><tr class="table-row" id="example-table-sticky-header-record-3" data-status="Review"><td class="table-cell" id="example-table-sticky-header-record-name-3">Signal monitor</td><td class="table-cell">Riley Stone</td><td class="table-cell">Review</td><td class="table-cell">6</td></tr><tr class="table-empty" hidden=""><td class="table-empty-cell" colspan="4">No rows match.</td></tr><tr class="table-loading" hidden=""><td colspan="4">⋯ Loading rows</td></tr></tbody></table></div></j3w1-table>numeric
| Atlas library | Avery Kim | Ready | 24 |
| Orion workspace | Jordan Lee | In progress | 12 |
| Field notes | Morgan Noor | Ready | 38 |
| Signal monitor | Riley Stone | Review | 6 |
| No rows match. | |||
| ⋯ Loading rows | |||
<j3w1-table id="example-table-numeric"><div class="table-scroller" tabindex="0" role="region" aria-label="Project records"><table class="table"><caption class="table-caption">Project records · synthetic fixture</caption><thead class="table-head"><tr><th class="table-header" scope="col"><button class="table-sort" type="button">Project<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Owner<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Status<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Scope<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th></tr></thead><tbody class="table-body"><tr class="table-row" id="example-table-numeric-record-0" data-status="Ready"><td class="table-cell" id="example-table-numeric-record-name-0">Atlas library</td><td class="table-cell">Avery Kim</td><td class="table-cell">Ready</td><td class="table-cell">24</td></tr><tr class="table-row" id="example-table-numeric-record-1" data-status="In progress"><td class="table-cell" id="example-table-numeric-record-name-1">Orion workspace</td><td class="table-cell">Jordan Lee</td><td class="table-cell">In progress</td><td class="table-cell">12</td></tr><tr class="table-row" id="example-table-numeric-record-2" data-status="Ready"><td class="table-cell" id="example-table-numeric-record-name-2">Field notes</td><td class="table-cell">Morgan Noor</td><td class="table-cell">Ready</td><td class="table-cell">38</td></tr><tr class="table-row" id="example-table-numeric-record-3" data-status="Review"><td class="table-cell" id="example-table-numeric-record-name-3">Signal monitor</td><td class="table-cell">Riley Stone</td><td class="table-cell">Review</td><td class="table-cell">6</td></tr><tr class="table-empty" hidden=""><td class="table-empty-cell" colspan="4">No rows match.</td></tr><tr class="table-loading" hidden=""><td colspan="4">⋯ Loading rows</td></tr></tbody></table></div></j3w1-table>with-caption
| Atlas library | Avery Kim | Ready | 24 |
| Orion workspace | Jordan Lee | In progress | 12 |
| Field notes | Morgan Noor | Ready | 38 |
| Signal monitor | Riley Stone | Review | 6 |
| No rows match. | |||
| ⋯ Loading rows | |||
<j3w1-table id="example-table-with-caption"><div class="table-scroller" tabindex="0" role="region" aria-label="Project records"><table class="table"><caption class="table-caption">Project records · synthetic fixture</caption><thead class="table-head"><tr><th class="table-header" scope="col"><button class="table-sort" type="button">Project<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Owner<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Status<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th><th class="table-header" scope="col"><button class="table-sort" type="button">Scope<span class="table-sort-glyph" aria-hidden="true">↕</span></button></th></tr></thead><tbody class="table-body"><tr class="table-row" id="example-table-with-caption-record-0" data-status="Ready"><td class="table-cell" id="example-table-with-caption-record-name-0">Atlas library</td><td class="table-cell">Avery Kim</td><td class="table-cell">Ready</td><td class="table-cell">24</td></tr><tr class="table-row" id="example-table-with-caption-record-1" data-status="In progress"><td class="table-cell" id="example-table-with-caption-record-name-1">Orion workspace</td><td class="table-cell">Jordan Lee</td><td class="table-cell">In progress</td><td class="table-cell">12</td></tr><tr class="table-row" id="example-table-with-caption-record-2" data-status="Ready"><td class="table-cell" id="example-table-with-caption-record-name-2">Field notes</td><td class="table-cell">Morgan Noor</td><td class="table-cell">Ready</td><td class="table-cell">38</td></tr><tr class="table-row" id="example-table-with-caption-record-3" data-status="Review"><td class="table-cell" id="example-table-with-caption-record-name-3">Signal monitor</td><td class="table-cell">Riley Stone</td><td class="table-cell">Review</td><td class="table-cell">6</td></tr><tr class="table-empty" hidden=""><td class="table-empty-cell" colspan="4">No rows match.</td></tr><tr class="table-loading" hidden=""><td colspan="4">⋯ Loading rows</td></tr></tbody></table></div></j3w1-table>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@4.0.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/table.css';
import '@j3w1/ui/register/table';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy table --out ./vendor/j3w1/tableThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
sort | (column: number, direction?: 'ascending' | 'descending'): void | Sort existing native rows by a column. |
filter | (query: string): void | Filter existing rows by literal text. |
events
| Name | Type / signature | Meaning |
|---|---|---|
j3w1-sort | CustomEvent | The user requested sorting. |
j3w1-selection | CustomEvent | Selected row identities changed. |
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Table table
A native data table with a header rule, row dividers, hover and selection fills, sortable headers with a glyph, and static empty and loading rows.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
root.bg | color.surface.defaultapproveduse | #0d0707 | D-041 surface.default: color.primitive.modern.panel. |
header.text | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
header.bg | color.surface.defaultapproveduse | #0d0707 | D-041 surface.default: color.primitive.modern.panel. |
header.rule | color.border.strongobserveduse | #9e231f | Emphasised 2px rule: sticky headers, section ends. |
header.bg-sticky | color.surface.raisedapproveduse | #140b0b | D-041 surface.raised: color.primitive.modern.raised. |
sort.glyph | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
sort.ring | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
row.text | color.text.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
row.divider | color.border.dividerapproveduse | #482b2b | D-041 border.divider: color.primitive.modern.divider. |
row.bg-hover | color.interaction.hover.bgapproveduse | #1c1010 | D-041 interaction.hover.bg: color.primitive.modern.hover. |
selected.bg | color.interaction.selection.bgapproveduse | #531310 | Selected row, tab, workspace; D-027 recessed the fill, leaving the 2px indicator and the check to carry selection. |
selected.text | color.interaction.selection.textobserveduse | #f4eeee | Text on the selection. |
selected.ring | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
selected.inactive-bg | color.interaction.selection.inactive-bgobserveduse | #420f0c | Selection while the container is not focused. |
selected.inactive-text | color.interaction.selection.inactive-textapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
caption.text | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
empty.text | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
loading.glyph | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Default | Sticky header | Numeric | With caption | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
default |
|
|
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hover | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
selected | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
selected+focus-visible | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
selected+container-inactive | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sorted | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
empty | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
loading | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Purpose
Records as rows, attributes as columns, compared down a column. For
reading only: selection, resizing and a toolbar make it a data-table; a
single column of rows is a list.
Anatomy
Parts as listed in the anatomy; the sticky header sits on
color.surface.raised.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | rows on color.surface.default; header rule 1px color.border.strong | — |
| hover | row → color.interaction.hover.bg | cursor: default; hover-capable pointers only |
| selected | row fill color.interaction.selection.bg; every cell color.interaction.selection.text | aria-selected="true" on the row |
| selected+focus-visible | the fill and 1px dashed color.interaction.focus.ring at −2px around the row | both visible at once |
| selected+container-inactive | row fill color.interaction.selection.inactive-bg with color.interaction.selection.inactive-text; no ring | lightness drop between the two fills |
| sorted | ▲ (ascending) or ▼ (descending) in color.text.bright on the sorted header | aria-sort; the glyph |
| empty | one full-width cell in color.text.muted: “No rows match.” | the message text |
| loading | one full-width cell with the static ⋯ glyph in color.text.muted; the header stays | aria-busy="true"; the glyph; no animation |
Precedence: loading > empty; selected > hover; focus-visible is always drawn.
Keyboard
As in the key table. Rows that are targets (row links, row selection) make
it a data-table, which adds row focus.
Accessibility
caption or aria-labelledby names the table; scope="row" on a row
header column. aria-sort is none or absent on unsorted headers; the
glyph is aria-hidden. Empty and loading rows are real rows; a live region
reports the loading outcome. Text meets 4.5:1; rings 3:1. Rows are at least
24 CSS pixels tall; sort buttons fill the header cell.
Portability
Row backgrounds, one border under the header, one between rows, an outline on a selected row. Native table views take the rule, the divider and the two fills. A host that cannot outline a row draws the ring as an inset 1px border and records it.
Non-examples
Zebra striping. A rounded or bordered frame. A selected row marked by a
left bar (that is navigation). Header text in caption size or uppercase.
Sorting by colour alone without aria-sort and a glyph. An animated
spinner. An empty state that removes the header. Truncated text with no way
to read the full value. Hover fill on touch.
Contrast report
15 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| table default text | default | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| table hover text | hover | text | color.text.default #e99499 | color.interaction.hover.bg #1c1010 | 8.10 | 4.5 | pass |
| table selected text | selected | text | color.interaction.selection.text #f4eeee | color.interaction.selection.bg #531310 | 12.47 | 4.5 | pass |
| table selected+focus-visible text | selected+focus-visible | text | color.interaction.selection.text #f4eeee | color.interaction.selection.bg #531310 | 12.47 | 4.5 | pass |
| table selected+focus-visible outline | selected+focus-visible | ui | color.interaction.focus.ring #e53935 | color.interaction.selection.bg #531310 | 3.38 | 3 | pass |
| table selected+container-inactive text | selected+container-inactive | text | color.interaction.selection.inactive-text #e99499 | color.interaction.selection.inactive-bg #420f0c | 7.02 | 4.5 | pass |
| table sorted text | sorted | text | color.text.bright #ffa2a7 | color.surface.default #0d0707 | 10.45 | 4.5 | pass |
| table empty text | empty | text | color.text.muted #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
| table loading text | loading | text | color.text.muted #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
| header text | — | text | color.text.bright #ffa2a7 | color.surface.default #0d0707 | 10.45 | 4.5 | pass |
| sticky header text on the raised surface | — | text | color.text.bright #ffa2a7 | color.surface.raised #140b0b | 10.14 | 4.5 | pass |
| caption | — | text | color.text.muted #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
| ring on a sort button | — | ui | color.interaction.focus.ring #e53935 | color.surface.default #0d0707 | 4.73 | 3 | pass |
| header rule (decorative; thead carries the structure) | — | ui | color.border.strong #9e231f | color.surface.default #0d0707 | 2.58 | 1 | pass |
| row divider (decorative) | — | ui | color.border.divider #482b2b | color.surface.default #0d0707 | 1.58 | 1 | pass |
Keys
| Key | Action |
|---|---|
| Tab / Shift+Tab | Moves between the sort buttons and any controls inside cells; rows themselves are not tab stops in a plain table. |
| Enter / Space | Toggles the sort of the focused header between ascending and descending. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: data-table list pagination badge filterable-table
Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-DENSITY FX-OVERFLOW FX-STATE-MATRIX