# View

> Package `@umriss-ui/table`, version 0.40.0. Demo page: <https://romanhaendler.github.io/umriss-ui/table/view/>. Every page in one line: [llms.txt](https://romanhaendler.github.io/umriss-ui/table/llms.txt); every page in full: [llms-full.txt](https://romanhaendler.github.io/umriss-ui/table/llms-full.txt).

What the user did to the table – search, conditions, sort, hidden columns, widths, page – as one value to keep and hand back.

```ts
import { useTable } from "@umriss-ui/table";
```

Demo page: https://romanhaendler.github.io/umriss-ui/table/view/

The table remembers nothing, not in the address and not in any storage. Everything stands in `t.view`, and `onViewChange` reports every change of it; keep it where the application keeps things. `initialView` is read once; `t.setView(view)` goes to another view later and is not reported through `onViewChange`, so two tables stay in step by `onViewChange: (v) => other.setView(v)` in both directions.

## Examples

### Keep and restore a view

`t.view` holds search, sort, hidden columns and widths as one value; keep one and go back to it with `t.setView`, no `key` needed. Sort, hide, drag a width, then restore.

```tsx
import { useState } from "react";
import { Button, Stack, Text } from "@umriss-ui/core";
import { ColumnMenu, Search, Toolbar, useTable } from "@umriss-ui/table";
import type { TableView } from "@umriss-ui/table";

const START_VIEW: TableView = {
  sort: [{ column: "amount", direction: "desc" }],
  hidden: ["costCentre"],
};

interface Invoice {
  id: string;
  supplier: string;
  costCentre: string;
  amount: number;
}

const INVOICES: Invoice[] = [
  { id: "INV-26-0318", supplier: "Brandlow Office Supply", costCentre: "Facilities", amount: 1951.24 },
  { id: "INV-26-0317", supplier: "Kettering & Shaw Events", costCentre: "Marketing", amount: 15110 },
  { id: "INV-26-0309", supplier: "Nimbrel Software", costCentre: "IT", amount: 7288 },
  { id: "INV-26-0302", supplier: "Fenwright Legal", costCentre: "Finance", amount: 3770 },
];

export default function InitialView() {
  /* The table holds its view and starts from `initialView`; `t.view` is what
     it shows now, and `t.setView` restores a kept one. */
  const [kept, setKept] = useState<TableView | null>(null);
  const [reports, setReports] = useState(0);
  const t = useTable(INVOICES, { rowKey: (i) => i.id, initialView: START_VIEW, onViewChange: () => setReports((n) => n + 1) });
  const { Table, Column, view, setView } = t;

  return (
    <Stack gap={3}>
      <Table ariaLabel="Invoices">
        <Toolbar>
          <Search placeholder="Invoice or supplier" />
          <ColumnMenu />
        </Toolbar>
        <Column value="id" label="Invoice" rowHeader />
        <Column value="supplier" label="Supplier" resizable />
        <Column value="costCentre" label="Cost centre" />
        <Column value="amount" label="Amount (€)" format={{ decimals: 2 }} />
      </Table>
      <Stack gap={1}>
        <Text as="span" size="sm" tone="secondary">
          What the application would keep - reported {reports} times; a restore is not a report
        </Text>
        {/* JSON has no space to break at: without this it ran past a phone's card. */}
        <Text as="code" size="sm" mono data-role="view" style={{ overflowWrap: "anywhere" }}>
          {JSON.stringify(t.view)}
        </Text>
      </Stack>
      <Stack direction="row" gap={2} wrap>
        <Button size="sm" onClick={() => setKept(view)}>
          Keep this view
        </Button>
        <Button size="sm" variant="ghost" disabled={kept === null} onClick={() => kept && setView(kept)}>
          Restore the kept view
        </Button>
        <Button size="sm" variant="ghost" onClick={() => setView(START_VIEW)}>
          Back to the beginning
        </Button>
      </Stack>
    </Stack>
  );
}
```

## Keyboard

The keys of [First table](https://romanhaendler.github.io/umriss-ui/table/first-table/#keyboard-first-table), [Input](https://romanhaendler.github.io/umriss-ui/core/input/#keyboard-input), [ColumnMenu](https://romanhaendler.github.io/umriss-ui/table/columnmenu/#keyboard-columnmenu) and [Button](https://romanhaendler.github.io/umriss-ui/core/button/#keyboard-button) apply here.

## Props on this page

From `TableProps` — the full table stands on [First table](https://romanhaendler.github.io/umriss-ui/table/first-table/#type-TableProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`children`](https://romanhaendler.github.io/umriss-ui/table/first-table/#TableProps-children) | `ReactNode` | — | Columns, `RowDetail`, `RowActions` and the unbound parts. |

#### Accessibility

| Prop | Type | Default | Description |
|---|---|---|---|
| [`ariaLabel`](https://romanhaendler.github.io/umriss-ui/table/first-table/#TableProps-ariaLabel) | `string` | — | Accessible name of the table (not of the outer frame). |

From `TableOptions` — the full table stands on [First table](https://romanhaendler.github.io/umriss-ui/table/first-table/#type-TableOptions).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`rowKey`](https://romanhaendler.github.io/umriss-ui/table/first-table/#TableOptions-rowKey) *required* | `(row: Z) => string` | — | A stable key per row – the basis of selection and expansion. |
| [`initialView`](https://romanhaendler.github.io/umriss-ui/table/first-table/#TableOptions-initialView) | [`TableView`](https://romanhaendler.github.io/umriss-ui/table/first-table/#type-TableView) | — | The view to start from, read once when the hook first runs; a different value on a later render is ignored, as React ignores a changed `defaultValue`. To go to a view later, call `setView`. The table remembers none: where a view is kept is the application's decision. Names no column carries fall out. |

#### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| [`onViewChange`](https://romanhaendler.github.io/umriss-ui/table/first-table/#TableOptions-onViewChange) | `(view: `[`TableView`](https://romanhaendler.github.io/umriss-ui/table/first-table/#type-TableView)`) => void` | — | Every change the reader makes, once, always the whole view - the one to keep, or to hand another table's `setView`. Not called for the view the table starts with, nor for one `setView` applies. |

From `TableSnapshot` — the full table stands on [First table](https://romanhaendler.github.io/umriss-ui/table/first-table/#type-TableSnapshot).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`setView`](https://romanhaendler.github.io/umriss-ui/table/first-table/#TableSnapshot-setView) *required* | `(view: `[`TableView`](https://romanhaendler.github.io/umriss-ui/table/first-table/#type-TableView)`) => void` | — | Goes to a whole view; what it leaves out goes back to where the table starts, and names no column carries fall out. Not reported through `onViewChange`: two tables kept in step by `onViewChange: (v) => other.setView(v)` in both directions do not answer each other. A view with the content already shown changes nothing. |
| [`view`](https://romanhaendler.github.io/umriss-ui/table/first-table/#TableSnapshot-view) *required* | [`TableView`](https://romanhaendler.github.io/umriss-ui/table/first-table/#type-TableView) | — | The part of the state an application can keep; whatever still stands as the options set it up is absent. |

From `FieldColumn` — the full table stands on [Column](https://romanhaendler.github.io/umriss-ui/table/column/#type-FieldColumn).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`value`](https://romanhaendler.github.io/umriss-ui/table/column/#FieldColumn-value) *required* | `K` | — | A field of the row. Supplies the column's `id` at the same time. |
| [`format`](https://romanhaendler.github.io/umriss-ui/table/column/#FieldColumn-format) | [`FormatFor`](https://romanhaendler.github.io/umriss-ui/table/column/#type-FormatFor)`<Z[K]>` | — | A standard presentation by name: `"percent"`, `"count"` or `{ decimals }` for numbers, `"date"`, `"time"` or `"dateTime"` for points in time. Alignment, sorting, export and footer stay with the value. |

From `ColumnBase` — the full table stands on [Column](https://romanhaendler.github.io/umriss-ui/table/column/#type-ColumnBase).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`label`](https://romanhaendler.github.io/umriss-ui/table/column/#ColumnBase-label) *required* | `string` | — | Names the column in its header, in the column menu and in the header row of the export. |
| [`rowHeader`](https://romanhaendler.github.io/umriss-ui/table/column/#ColumnBase-rowHeader) | `boolean` | — | This column names the row: row header cells, never hideable, the column `stickyRowHeader` pins, and the name by which the row's selection, expander and actions are read out. At most one per table. |
| [`resizable`](https://romanhaendler.github.io/umriss-ui/table/column/#ColumnBase-resizable) | `boolean` | — | Shows the drag grip on the header cell. |

From `SearchProps` — the full table stands on [Search](https://romanhaendler.github.io/umriss-ui/table/search/#type-SearchProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`placeholder`](https://romanhaendler.github.io/umriss-ui/table/search/#SearchProps-placeholder) | `string` | the wording's "Search …" | The placeholder in the field. |

From `ToolbarProps` — the full table stands on [Toolbar](https://romanhaendler.github.io/umriss-ui/table/toolbar/#type-ToolbarProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`children`](https://romanhaendler.github.io/umriss-ui/table/toolbar/#ToolbarProps-children) | `ReactNode` | — | Search, column menu, export – on the left in the table toolbar, before the conditions. |