useListView
The state of a list view: filters and display options, and the records they select, grouped and ordered.
import { useListView, viewRecords, type ViewSpec } from "@forgeron/ui";NEW
Domaine Vidal 4,200
PROPOSAL
Clinique Saint-Luc 31,000
Brasserie du Port 8,400
WON
Atelier Morel 12,000
// The state of a view without its chrome: filters, grouping and ordering applied to plain records.
import { FilterBar, FilterMenu, useListView, type ViewSpec } from "@forgeron/ui";
import { Loading03Icon } from "@forgeron/icons";
interface Lead {
name: string;
stage: string;
value: number;
}
const leads: Lead[] = [
{ name: "Atelier Morel", stage: "won", value: 12_000 },
{ name: "Brasserie du Port", stage: "proposal", value: 8_400 },
{ name: "Clinique Saint-Luc", stage: "proposal", value: 31_000 },
{ name: "Domaine Vidal", stage: "new", value: 4_200 },
];
const STAGES = ["new", "proposal", "won"];
const spec: ViewSpec<Lead> = {
read: (lead, field) => (field === "stage" ? lead.stage : null),
groupings: { stage: { key: (l) => l.stage, order: STAGES } },
orderings: { value: (a, b) => b.value - a.value },
};
export default function FilterGroupOrder() {
const view = useListView(leads, spec, {
defaultDisplay: {
layout: "list",
grouping: "stage",
ordering: "value",
toggles: {},
properties: [],
},
});
const fields = [
{
id: "stage",
label: "Stage",
icon: Loading03Icon,
options: STAGES.map((s) => ({ value: s, label: s })),
},
];
return (
<div style={{ width: "100%", maxWidth: 420, display: "grid", gap: 8 }}>
<div style={{ display: "flex", gap: 8 }}>
<FilterMenu fields={fields} value={view.filters} onChange={view.setFilters} />
</div>
<FilterBar fields={fields} value={view.filters} onChange={view.setFilters} />
{view.groups.map((g) => (
<section key={g.key}>
<p
className="t-mono"
style={{ margin: "8px 0 4px", color: "var(--ink-dim)", fontSize: 11 }}
>
{g.name.toUpperCase()}
</p>
{g.records.map((l) => (
<p
key={l.name}
style={{ margin: 0, display: "flex", justifyContent: "space-between", fontSize: 13 }}
>
{l.name} <span className="t-mono">{l.value.toLocaleString("en")}</span>
</p>
))}
</section>
))}
</div>
);
}API → Props
| Prop | Type | Default | Description |
|---|---|---|---|
records | T[] | — | Every record of the view. |
spec | { read, groupings?, orderings? } | — | read(record, field) for the filters (null matches “_”); groupings by id: { key, order?, name? }; orderings by id: a comparison. |
defaultDisplay / defaultFilters | DisplayOptions / Filter[] | — | Where the view starts, and where Reset to default goes back to. |
returns | ListView<T> | — | filters, setFilters, display, setDisplay, setLayout, records, groups, defaultDisplay. A showEmptyGroups toggle keeps empty groups. viewRecords does the same without React. |