# @umriss-ui/table

> React data table for data-dense applications - sorting, filtering, grouping, aggregates, virtualisation. Declared the way it reads: columns as JSX, typed against their rows.

Version 0.13.6. Install with `npm install @umriss-ui/table @umriss-ui/core`. Each link below leads to that page as Markdown. Every page below in full - its examples' source, its props tables generated from the code, and what it deliberately does not do - stands in one file: [llms-full.txt](https://romanhaendler.github.io/umriss-ui/table/llms-full.txt). The npm package carries the same text for the installed version as `docs/llms-full.md`; prefer that one when the package is installed.

## Scenarios

Composed, realistic screens built from the package.

- [Work through the alerts](https://romanhaendler.github.io/umriss-ui/table/index.md): The on-call engineer at Quillmere opens the alert list, takes the worst first, acknowledges what they have seen and snoozes what can wait.
- [Find a late shipment](https://romanhaendler.github.io/umriss-ui/table/index.md): A dispatcher at Ferrow Parcel answers a customer's call: finds the shipment, sees whether it missed its window, and tidies the day's list.
- [Review cost centres against budget](https://romanhaendler.github.io/umriss-ui/table/index.md): The controller at Carrow & Lisle reviews the first quarter before the month-end call: which cost centres will land over budget, and by how much.
- [Plan the team's capacity](https://romanhaendler.github.io/umriss-ui/table/index.md): Tidewell's delivery lead fills in the hours each person is booked for the next three weeks, and sees at once who is booked beyond what they have.

## Getting started

What an application sets up once, before its first table.

- [Installation](https://romanhaendler.github.io/umriss-ui/table/installation.md): Two packages, no stylesheet to import, and one hook that turns an array of rows into a table.
- [First table](https://romanhaendler.github.io/umriss-ui/table/first-table.md): Rows of records to scan, sort, search and select (also called a data table or data grid). Reach for it when people compare many records by the same fields; from a few rows to a million on a server.
- [Provider](https://romanhaendler.github.io/umriss-ui/table/provider.md): Set the table's wording, formats and density once for the whole application, at the core package's `UmrissProvider`.

## Columns

What a column reads, how it shows it, and how wide it stands.

- [Column](https://romanhaendler.github.io/umriss-ui/table/column.md): One value per row, read from a field or computed. Everything the table does with a column (sort, search, export, total) works on that value, never on what the cell shows.
- [Formats](https://romanhaendler.github.io/umriss-ui/table/formats.md): How a value looks in its cell: a standard format, a presentation of its own, an absent value and a long one.
- [Width and pinning](https://romanhaendler.github.io/umriss-ui/table/width-and-pinning.md): How wide a column stands, which columns stay in view while the table scrolls sideways (frozen or sticky columns), and a header that stays while it scrolls down.
- [Presets](https://romanhaendler.github.io/umriss-ui/table/presets.md): A column written once and used in many tables: as a preset spread into a column, or as a component that brings its own presentation.

## Finding rows

How a user gets from many rows to the ones that matter.

- [Sorting](https://romanhaendler.github.io/umriss-ui/table/sorting.md): Order the rows by a column, and by further columns where the first ties. Reach for a sort order of your own where the value is an object.
- [Search](https://romanhaendler.github.io/umriss-ui/table/search.md): A text field that narrows the table to the rows containing what the user types (also called a quick filter or global filter). Put it in the toolbar, or anywhere on the page.
- [Filter](https://romanhaendler.github.io/umriss-ui/table/filter.md): Narrow a column to some of its values: those that occur, a range between two bounds, or a condition the application defines. Reach for it when people look for records by a field rather than by free text.
- [Pre-filter](https://romanhaendler.github.io/umriss-ui/table/pre-filter.md): Decide which rows a table has at all – by permission, by site, by tenant. The user never sees it, cannot lift it, and it is not part of the view.

## Grouping

What rows have in common, read at a glance: groups on up to three levels, and what their values come to.

- [Grouping](https://romanhaendler.github.io/umriss-ui/table/grouping.md): Gather rows that share a value under one header with their count and totals (also called row grouping). Reach for it when the question is per customer, per team or per month rather than per record.
- [Tree rows](https://romanhaendler.github.io/umriss-ui/table/tree-rows.md): Rows that hold rows: a hierarchy of any number of levels whose every level carries the same figures (also called tree data). Reach for it to drill down an organisation, regions and places or cost centres - levels the application holds, uneven as they are.
- [Aggregate](https://romanhaendler.github.io/umriss-ui/table/aggregate.md): What a column's values come to: a sum, an average, the extremes, a count. It stands in the footer over the filtered rows and in each group header over the group's rows.

## Rows

What a row carries besides its values: a tick, a look, a detail and actions.

- [Selection](https://romanhaendler.github.io/umriss-ui/table/selection.md): Tick rows to act on them together (also called row selection or multi-select).
- [Row appearance](https://romanhaendler.github.io/umriss-ui/table/row-appearance.md): How rows look: dense or regular, marked by their state, and what stands while rows load, fail or do not exist.
- [RowDetail](https://romanhaendler.github.io/umriss-ui/table/rowdetail.md): More about a row, opened beneath it on demand (also called an expandable or master-detail row). Reach for it when a row needs facts, notes or a small table of its own that would crowd the columns.
- [RowActions](https://romanhaendler.github.io/umriss-ui/table/rowactions.md): Buttons at the end of each row for what the user does to that row – open, approve, reject. Mark one as a bulk action and it also acts on every ticked row at once.

## Around the table

The bar above the table, what it holds, and the view a table can hand back.

- [Toolbar](https://romanhaendler.github.io/umriss-ui/table/toolbar.md): The bar above the table that holds its search, column menu and export, shows how many rows match, and carries the bulk actions while rows are ticked (also called a table header bar).
- [Toolbar controls](https://romanhaendler.github.io/umriss-ui/table/toolbar-controls.md): Put controls of your own into the toolbar - a multiselect, a select, a combobox - and let them stand level with the table's: one size for the whole bar, and a row filter behind each control.
- [ColumnMenu](https://romanhaendler.github.io/umriss-ui/table/columnmenu.md): A menu in which the user shows, hides, reorders and pins the table's columns and picks a grouping (also called a column chooser). Offer it where the table has more columns than everyone needs.
- [Export](https://romanhaendler.github.io/umriss-ui/table/export.md): A button that writes the rows the user sees into a CSV file for a spreadsheet (also called download or export to Excel). Hand the application the text instead where it wants the clipboard or a file of its own.
- [View](https://romanhaendler.github.io/umriss-ui/table/view.md): What the user did to the table – search, conditions, sort, hidden columns, widths, page – as one value to keep and hand back.

## Many rows

Tables of thousands of rows, in the browser or on a server.

- [Pagination](https://romanhaendler.github.io/umriss-ui/table/pagination.md): The bar under the table that splits long results into pages, with the page size to choose (also called a pager). The table pages only where one stands; without it every filtered row is shown.
- [Virtualisation](https://romanhaendler.github.io/umriss-ui/table/virtualisation.md): Thousands of rows the user scrolls through without pages: only the rows in view are rendered, and everything else still reaches every row.
- [Server mode](https://romanhaendler.github.io/umriss-ui/table/server-mode.md): A table over rows a server holds: the application hands in one page and the server's count, and the table reports what to fetch next (also called server-side paging, sorting and filtering).

## Editing

Working in the cells instead of reading them.

- [Grid mode](https://romanhaendler.github.io/umriss-ui/table/grid-mode.md): Make the table one Tab stop whose cells the arrow keys walk, as in a spreadsheet. It is the mode for editing; keep it off for tables that are only read.
- [Edits](https://romanhaendler.github.io/umriss-ui/table/edits.md): Let people change a value in its cell. The table reports each edit, and the application writes it into its rows.

## Limits and alarms

A reading, read against its limits - and alarms with a lifecycle.

- [VerdictColumn](https://romanhaendler.github.io/umriss-ui/table/verdictcolumn.md): A column that judges each value against limits – ok, warning, alarm or unknown – and shows by how much it is out (also called a threshold or status column). Use it wherever a number has a line it must not cross.
- [AlarmList](https://romanhaendler.github.io/umriss-ui/table/alarmlist.md): The list of alerts someone has to see and acknowledge, worst first, with their state, age and frequency (also called an alarm or alert console). Reach for it wherever alerts arrive and a person answers for them.

## API index

Every name the package exports, in one place.

- [API index](https://romanhaendler.github.io/umriss-ui/table/api.md): Everything `@umriss-ui/table` exports, with its signature. A component's props stand on its own page.