@omega/table (0.1.1)
Installation
@omega:registry=npm install @omega/table@0.1.1"@omega/table": "0.1.1"About this package
@omega/table
DataTable is the styled table facade over TanStack Table. Applications own
data loading and business behavior; the package owns table state, rendering,
accessibility, selection, filtering, column layout, and virtualization.
Styling contract
Import @omega/table/styles.css. Package styles consume the shared
--spp-ui-* theme tokens and expose stable semantic --spp-ui-table-*
properties. Add an application class through className and override tokens on
the same element:
<DataTable className="orders-table" data={rows} columns={columns} />
.orders-table {
--spp-ui-table-cell-px: 8px;
--spp-ui-table-cell-py: 4px;
--spp-ui-table-header-height: 36px;
--spp-ui-table-font-size: 13px;
--spp-ui-table-border-radius: 4px;
}
The defaults use :where(.spp-ui-table-root, .spp-ui-table__popover), so an
application class on the table root wins without !important. Portaled column
menu and filter popovers also carry the token defaults (and data-density)
because they render outside the table tree.
Public semantic tokens
- Surfaces:
--spp-ui-table-bg-surface,--spp-ui-table-bg-header,--spp-ui-table-bg-row,--spp-ui-table-bg-row-hover,--spp-ui-table-bg-row-selected,--spp-ui-table-bg-row-selected-hover,--spp-ui-table-bg-pinned. - Borders and typography:
--spp-ui-table-border-color,--spp-ui-table-border-radius,--spp-ui-table-font-size,--spp-ui-table-header-font-weight. - Density and spacing:
--spp-ui-table-row-height,--spp-ui-table-header-height,--spp-ui-table-cell-px,--spp-ui-table-cell-py,--spp-ui-table-header-cell-px,--spp-ui-table-floating-filter-py. - Controls and menus:
--spp-ui-table-header-action-size,--spp-ui-table-control-radius,--spp-ui-table-control-hover-bg,--spp-ui-table-menu-min-width,--spp-ui-table-menu-item-min-height,--spp-ui-table-menu-item-padding. - Feedback:
--spp-ui-table-highlight-duration,--spp-ui-table-highlight-added-bg,--spp-ui-table-highlight-updated-bg,--spp-ui-table-highlight-deleted-bg,--spp-ui-table-row-disabled-opacity,--spp-ui-table-row-removing-opacity,--spp-ui-table-row-placeholder-opacity. - Overlays and popovers:
--spp-ui-table-overlay-min-height,--spp-ui-table-overlay-padding,--spp-ui-table-popover-min-width,--spp-ui-table-popover-bg,--spp-ui-table-popover-shadow,--spp-ui-table-popover-padding,--spp-ui-table-popover-gap.
Sticky positioning, z-indexes, table layout, and virtualization geometry are implementation details and are intentionally not theme tokens.
Layout and sizing
DataTable fills the size of its container (the AG Grid / MUI DataGrid model):
the root is a flex column with flex: 1 1 0% and height: 100%, only the body
scrolls, and the header, footer, and state overlays (loading / empty / error)
stay pinned within the same region. This avoids layout shift when rows arrive
or the table becomes empty.
The container must provide a definite size — typically a flex chain with
min-height: 0 at every level:
.screen-root {
display: flex;
flex-direction: column;
height: 100%; /* not `max-height`: the table fills the screen, it does not grow with content */
}
If the container has no definite height, the table degrades gracefully to
content height (embedded scenarios). To keep a content-sized table inside a
flex container, opt out explicitly via className:
.embedded-table {
flex: 0 0 auto;
height: auto;
}
Density
density provides coherent compact, standard, and comfortable presets.
It changes semantic row/header tokens and the default virtualization estimate.
Header vertical size is owned by --spp-ui-table-header-height (not padding).
Explicit CSS token values can refine a preset; an explicit
virtualization.estimateRowHeight takes precedence over its estimate.
Locale
Package defaults are Russian (defaultDataTableLocaleText /
ruDataTableLocaleText). For English UI pass the EN pack:
import { DataTable, enDataTableLocaleText } from '@omega/table';
<DataTable data={rows} columns={columns} localeText={enDataTableLocaleText} />;
Partial overrides still work; nested filterOperators merges correctly via
resolveDataTableLocaleText(overrides) (or with an explicit base).
Customization levels
- CSS variables and
densityfor visual customization. - Column definitions, metadata, class/style resolvers, and locale text.
- Slots and column-menu command customization for structural replacement.
useDataTableInstance,tableRef, andapiReffor advanced integrations.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @dnd-kit/core | ^6.3.1 |
| @dnd-kit/sortable | ^10.0.0 |
| @dnd-kit/utilities | ^3.2.2 |
| @omega/icons | 0.2.0 |
| @omega/ui | 0.2.0 |
| classnames | 2.5.1 |
Development Dependencies
| ID | Version |
|---|---|
| @tanstack/react-table | 8.21.3 |
| @tanstack/react-virtual | 3.14.6 |
Peer Dependencies
| ID | Version |
|---|---|
| @tanstack/react-table | >=8.20.0 |
| @tanstack/react-virtual | >=3.13.0 |
| react | >=18.3.0 |
| react-dom | >=18.3.0 |
Optional Dependencies
| ID | Version |
|---|---|
| @tanstack/react-table | 8.21.3 |
| @tanstack/react-virtual | 3.14.6 |