tally-react
v0.1.2
Published
React hooks and component for Tally.
Readme
tally-react
React component and hooks for Tally. The engine lives in tally-core; this package renders it: virtualized rows and columns, pinned columns and rows, column groups, sorting, grouping, a natural-language filter bar with chips and typed popovers, inline editing with undo, fill handle, copy and paste, keyboard navigation, conditional formatting, a column menu, row context menu, footer aggregates, offset or cursor pagination and a card layout for narrow viewports.
Not published yet.
Install
npm install tally-react tally-core react react-domReact 19 or newer.
Usage
import { createArraySource, createSchema } from 'tally-core'
import { Tally, useGrid } from 'tally-react'
import 'tally-react/styles.css'
const schema = createSchema({
key: 'id',
columns: [
{ id: 'account', label: 'Account', pin: 'left' },
{ id: 'plan', type: 'enum', options: [{ value: 'free' }, { value: 'pro' }, { value: 'team' }] },
{ id: 'mrr', label: 'MRR', type: 'currency', aggregate: 'sum' },
{ id: 'growth', type: 'percent' },
{ id: 'renewal', type: 'date' },
],
})
function Accounts({ rows }) {
const [source] = useState(() => createArraySource(rows, schema))
const grid = useGrid({ schema, source })
return <Tally grid={grid} label="Accounts" />
}useGrid creates a Grid from tally-core, loads it on mount and disposes it on unmount. It recreates the grid when schema or source change identity, and when the format context changes, carrying the current view over.
<Tally>
| Prop | Type | Notes |
| -------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| grid | Grid | From useGrid or createGrid. |
| label | string | Accessible name of the grid, also the name of exported CSV files. |
| theme | 'light' \| 'dark' | Omit to follow prefers-color-scheme. |
| dir | 'ltr' \| 'rtl' | Omit to read the direction of the root or an ancestor. Pinning, arrows, resizing and menus follow it. |
| layout | 'auto' \| 'grid' \| 'cards' | auto switches to cards below cardsBelow pixels. |
| cardsBelow | number | Default 620. |
| detail | DetailRenderer \| boolean | Tapping a card opens a sheet with every visible field. false disables it, a function renders the sheet body. |
| toolbar | ReactNode \| boolean | true renders the default toolbar, false hides it, a node replaces it. |
| toolbarStart | ReactNode | Renders before the filter bar in the default toolbar, for tabs or titles. |
| ai | TallyAi | ask answers filter text that does not parse or reads like a sentence. addColumn enables the AI button, suggestions fill its list. |
| renderers | CellRenderers | Cell renderers by column type name or kind, merged over defaultRenderers. |
| editors | CellEditors | Cell editors by column type name or kind, merged over defaultEditors. |
| labels | Partial<TallyLabels> | Every string in the UI, merged over defaultLabels. |
| onIntent | (intent: GridIntent) => boolean \| undefined | Runs before the built-in handler. Return true to consume the intent. |
| initialSize | { width, height } | Viewport size before the first measurement, for server rendering and tests. |
| className, style | | Applied to the root element. |
Children render at the end of the default toolbar.
Hooks
| Hook | Returns |
| ----------------------------- | --------------------------------------------- |
| useGrid(options) | A Grid bound to the component lifecycle. |
| useGridState(grid, select?) | Status, totals, aggregates, facets and page. |
| useView(grid, select?) | The current View. |
| useRows(grid) | Loaded rows, their version and changed cells. |
| useSelection(grid) | Active cell, ranges and selected rows. |
| useColumnLayout(grid) | Visible columns with widths and pin edges. |
| useRowModel(grid) | Flattened rows, groups and pinned rows. |
| useGridContext() | The nearest Grid from GridProvider. |
| useViewUrl(grid, options?) | Nothing. Syncs the view with the URL. |
Selectors keep components from re-rendering when unrelated state changes.
View in the URL
useViewUrl keeps the view and the query string in sync. On mount a view in the URL replaces the current one, otherwise the current view is written to the URL. Later changes update the URL and popstate restores it. It only touches window inside effects, so it is safe to render on the server.
useViewUrl(grid)?q=status+is+active,+sort+by+mrr+desc,+group+by+renewal&granularity=month&density=compactFilter, sort and group are written as query language text. The rest is written only when it differs from the schema defaults: granularity, density, columns (order with :width, :2fr, :hidden, :left or :right per column), footer (column:aggregate pairs) and state (formatting rules, pinned, expanded and collapsed rows). Other parameters are left alone.
| Option | Type | Notes |
| --------- | ---------------------------------------- | --------------------------------------------------- |
| param | string | Parameter for the query text. Default q. |
| history | 'replace' \| 'push' | push adds a history entry per change. |
| encode | (view: View, search: string) => string | Returns the next query string. Replaces the format. |
| decode | (search: string) => View | Reads a view from the query string. |
The same format is available without React through viewToUrlString and viewFromUrlString in tally-core.
CSV
The Display menu exports and imports CSV. Export writes every row that matches the view, fetching remote pages through the source up to 100,000 rows, with the visible columns in view order, column labels as headers and raw values. Import matches headers to columns by id, label or alias, parses cells with the column types and inserts the rows as one mutation, so undo removes them. Rows without a free key get one from newRow. Problems show in the status banner.
Extending
Renderers and editors
A renderer receives the raw value, the formatted text, the row, the column, the column type and the format context. Keys match a column type name first, then its kind.
const renderers = {
currency: ({ text, value }) => <span data-negative={value < 0}>{text}</span>,
}
<Tally grid={grid} renderers={renderers} />A column with flex grows into spare viewport width in proportion to its value; its width stays the floor. The column menu toggles it with Fill remaining width, Fit width measures the rendered cells, and dragging a resize handle pins a fixed width again.
Four column options shape the default renderers: avatar draws an initials tile before a text value, subtitle names another column whose value sits under it, sparkline names a row field holding a numeric series drawn before a number, and relative adds a relative line such as "in 17 days" under a date. Subtitles and relative lines hide at compact density.
An editor receives commit(value, move?) and cancel(). move is 'down', 'up', 'right' or 'left' and decides where focus goes after the commit.
Labels
<Tally grid={grid} labels={{ filterPlaceholder: 'Filtern…', rows: (n) => `${n} Zeilen` }} />Default labels format their counts with the grid's format context, including numberingSystem. Overrides receive plain numbers.
The filter bar parses ASCII digits only; Arabic-Indic digits typed there match as text. Cell editors accept both.
Intents
Keyboard and mouse input becomes a GridIntent from tally-core. onIntent sees every intent first, so a host can bind its own command palette or inspector, or block an action.
<Tally
grid={grid}
onIntent={(intent) => {
if (intent.type === 'commandPalette') {
openPalette()
return true
}
return undefined
}}
/>Composition
The default toolbar is made of exported parts: Toolbar, FilterBar, Chip, DisplayMenu, Pager, HeaderMenu, RulesPopover and RowMenu. Pass toolbar={false} and render your own arrangement with useGridContext.
Styling
Import tally-react/styles.css once. The default type is Onest with JetBrains Mono for numbers; import tally-react/fonts.css to self-host both through @fontsource-variable/onest and @fontsource-variable/jetbrains-mono, or leave it out and the system stack takes over.
import 'tally-react/styles.css'
import 'tally-react/fonts.css'The stylesheet is unlayered and every selector is scoped under .tally, so it survives Tailwind's preflight and other resets without configuration. With Tailwind v4, import it into a layer when utilities should be able to override Tally classes:
@layer theme, base, tally, components, utilities;
@import 'tailwindcss';
@import 'tally-react/styles.css' layer(tally);Colors use light-dark() and follow color-scheme; override tokens on .tally or any ancestor:
.tally {
--tally-accent: oklch(0.6 0.18 30);
--tally-radius: 6px;
--tally-font: 'Inter', sans-serif;
--tally-row-height: 40px;
}Tokens: --tally-bg, --tally-canvas, --tally-soft, --tally-hover, --tally-ink, --tally-ink-2, --tally-ink-3, --tally-inverse, --tally-inverse-ink, --tally-line, --tally-line-2, --tally-line-strong, --tally-accent, --tally-up, --tally-up-soft, --tally-down, --tally-down-soft, --tally-warn, --tally-warn-ink, --tally-warn-soft, --tally-ai, --tally-ai-soft, --tally-ai-ink, --tally-selection, --tally-selection-row, --tally-ring, --tally-popup, --tally-radius, --tally-radius-sm, --tally-radius-xs, --tally-font, --tally-font-mono, --tally-font-size, --tally-row-height, --tally-header-height, --tally-group-height, --tally-group-band-height, --tally-footer-height, --tally-gutter-width, --tally-cell-padding.
State is exposed as data attributes for targeted overrides: data-density, data-theme, data-pin, data-pin-edge, data-sorted, data-active, data-range, data-selected, data-editing, data-sign, data-rule, data-layout.
Keyboard
| Keys | Action |
| ----------------------------------- | ------------------------------------ |
| Arrows, Home, End, PageUp, PageDown | Move the active cell |
| Shift + arrows | Extend the range |
| Cmd/Ctrl + arrows, Home, End | Jump to the edge |
| Tab, Shift + Tab | Next and previous cell |
| Enter, F2, typing | Edit the active cell |
| Escape | Cancel editing or clear the range |
| Shift + Space | Toggle the row |
| Space | inspect intent for the host |
| Alt + Left, Alt + Right | Collapse and expand a tree row |
| Delete, Backspace | Clear the range |
| Cmd/Ctrl + C, X, V | Copy, cut and paste as TSV |
| Cmd/Ctrl + Z, Shift + Z, Y | Undo and redo |
| Cmd/Ctrl + A | Select all cells |
| Cmd/Ctrl + K | commandPalette intent for the host |
| / | Focus the filter bar |
Under dir="rtl" Left and Right follow the screen, so Right moves to the previous column.
Bundle
Own code is under 23 kB brotli. With Base UI, TanStack Virtual, Pragmatic drag and drop and Lucide it is under 101 kB. tally-core, react and react-dom are not included in those numbers.
