React
On this page
@plurid/uitive-react connects a client to React 18.3 or 19: a provider, hooks that re-render only when what they read changes, a page renderer, the generic blocks, and the kit they are drawn with. Getting started builds a first integration; this page covers the whole package. The API reference is api/react.md.
The provider
UitiveProvider makes the client and the kit available to pages, generic blocks and confirmations below it. Mount it once, near the root, with Confirmations inside it.
export function Admin() {
return (
<UitiveProvider client={uitive} kit={kit}>
{/* Buttons and destructive runs wait for it; a form showing every value is the yes. */}
<Confirmations />
<OrdersPage />
</UitiveProvider>
);
}kitis what generic blocks are drawn with; it defaults to semantic HTML. See The kit.stylesadds the default kit's styles, which kits built withcreateKitstill use for layout. Turn it off when your design system styles everything.noncegoes on the kit's style element, for a Content Security Policy that allows inline styles only with a nonce: see Privacy and security.- The provider keeps the person's state across tab switches and visits: usage is saved whenever the page is hidden, and a new session starts when they come back after a while, which is when planned changes may apply.
Hooks
Every hook takes the client first.
| Hook | What it gives |
|---|---|
useSurface | A surface as this person has it: a list's visible and overflow actions, a choice's value, a collection, or a page |
useStandard | A surface as the application ships it |
useCommand | ask(text), with its pending state, result and error |
usePlan | plan(), with its pending state |
useAction | Runs one action from the application's own control, counted as use |
usePerform | Runs any action; writes wait for the person's yes |
useConfirmation | The run waiting for a yes, with confirm and cancel, for a confirmation of your own |
useQuery, useQueries | Query results, shared and cached |
useUitiveRouter | Connects your router: location in, links out |
useLocation | Where the person is, as the router last reported it |
useRanked | Every action, ranked by use, for a command palette |
useView | Whether the person sees their own interface or the standard one |
useLatest, usePending | The latest adaptation, and changes waiting for a safe moment |
useUserPages | The pages the person made |
useSnapshot | Everything the client holds, for panels; it changes with every use |
useLifecycle | What the provider does for state across visits, for a client used without it |
Server rendering draws the standard layout and the state of someone new, with no pages of their own and nothing pending, so hydration never mismatches; the person's own interface follows on the client.
Lists and choices
Draw a list from useSurface with your own components: its visible actions, then its overflow under a More menu or in a palette. Record each use with how it was reached, region or overflow, as the quick start's toolbar does: Getting started. An action with an effect can go through useAction instead, which records it.
A choice's value is a string; client.set changes it, as does a command naming a value. A collection gives items the person accepted and suggestions waiting, which client.accept(entry.operation) and client.dismiss(entry.operation) answer.
Pages
Page draws a page: sections, tabs, regions, the application's own blocks and the generic blocks.
export function OrdersPage() {
const value = useSurface(uitive, 'orders');
return <Page value={value} blocks={{}} regions={{ orders: OrdersList }} />;
}regionsgives each region its component: usually the existing page.blocksgives each of the application's own blocks its component, typed by the block's props withBlockComponents: see Pages.contextis the page's context value, andcurrentthe row it is about; by default, the row the location names. Blocks whose queries name$currentshow as loading until the row is known.- Each block sits in a wrapper with
data-blockanddata-elementattributes, and the page and its sections carrydata-layout, for styling;classNamereplaces the page'suitive-pageclass.
Routers
Tell the client where the person is on every route change, and let it follow links through your router. With React Router:
const location = useLocation();
const navigate = useNavigate();
useUitiveRouter(uitive, { path: location.pathname + location.search, navigate });With Next.js, useUitiveRouter(uitive, { path: usePathname(), navigate: useRouter().push }). Visiting a route records its action, and generated links and row links follow your routes.
Confirmations
<Confirmations /> asks before a generated page changes data: what the action does, every param it will run with, money in its own currency, and for a destructive one, the phrase to type. Mount it once inside the provider. Buttons and destructive runs wait for it, and without it they are refused. A generated form that shows every value it will send, parsed and with its currency, counts as the yes, so submitting it runs a write at once; one that can't show a value, such as the page's row before it is known, waits for <Confirmations /> instead. A block runs one action at a time, so pressing again while a run is in flight does nothing. For a confirmation of your own, useConfirmation gives the waiting run and the means to answer it.
The kit
Generic blocks draw only with the kit's parts, so mapping a part to your design system restyles every block that uses it. Start from the default and replace parts one at a time:
// The design system's parts, mapped one at a time; the rest of the default kit stays.
export const kit = createKit({
Title: ({ children }) => <h1 className="page-title">{children}</h1>,
Section: ({ title, children }) => (
<section className="card">
{title && <h2 className="card-title">{title}</h2>}
<div className="card-body">{children}</div>
</section>
),
Button: ({ children, onClick, tone = 'plain', disabled, type = 'button' }) => (
<button type={type} className={`button button-${tone}`} disabled={disabled} onClick={onClick}>
{children}
</button>
),
Notice: ({ tone, children }) => (
<p className={`notice notice-${tone}`} role="status">
{children}
</p>
),
});| Block | Parts |
|---|---|
| page, section, tabs | Title (a page's own heading), Section (a container and its title), Tabs |
| table | Table, Value for each cell, Button for row actions |
| list, timeline | List, Badge |
| detail | Grid, Text |
| metric | Stat, Value |
| chart | Chart |
| board | Grid, Card, List |
| form, actions | Stack, Field, Button, Text |
| note, links | Card, Text, Link |
| every block | Status (empty, loading, error, partial data), Notice after a run |
| confirmations, run forms | Dialog, Field, Button, Value |
- Blocks have no container of their own: map
Sectionto your card or panel when tables and lists should sit inside one. - The default
Dialogis a native modal<dialog>: it takes focus when it opens, keeps it inside, closes on Escape and gives focus back when it closes. ADialogof your own should do the same. - The default
Tabsmove with the arrow keys, Home and End, with one tab stop for the list. The defaultChartnever stacks or totals amounts in different currencies (a pie of several currencies shows as bars), and offers its figures as a visually hidden table;ChartPoint.currencysays which currency a point is in. Noticesays how a run ended. Map it to your toast: each run mounts a new one, so it can show itself when it mounts and render nothing.valueschanges how one kind of value shows everywhere, such asmoney, or one source's references, such as'ref:customers'.- The default kit reads
--uitive-accent,--uitive-on-accent,--uitive-surface,--uitive-text,--uitive-border,--uitive-radius,--uitive-gap,--uitive-good,--uitive-bad,--uitive-badgeand--uitive-dialog, so a theme can restyle it without replacing parts.
Every part and its props are in api/react.md.
The meta-interface
UitiveBanner says what just changed and why, with Revert, and Keep for changes the person didn't make, and answers commands, refusals included. UitiveYourInterface lists every change the person owns, with export, import, freeze and reset. UitiveDebug shows usage, requests and the planning loop, for development. Each takes the client, and registers its element the first time it renders.
- The banner floats at the bottom right;
dockedputs it in the page's flow, such as in your notification area. "Your interface" is a panel, for a settings page or a side panel.collapsedstarts the debug panel folded. classNameand these flags are set on the element directly, so React 18 and 19 render them alike.- Bundlers leave
UitiveDebugand its panel out of builds that never render it. - They render in shadow roots, styled with
--uitive-accent,--uitive-surface,--uitive-text,--uitive-muted,--uitive-border,--uitive-radiusand--uitive-font, with::part(content)and::part(heading)for more.