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.

tsx
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>
  );
}
  • kit is what generic blocks are drawn with; it defaults to semantic HTML. See The kit.
  • styles adds the default kit's styles, which kits built with createKit still use for layout. Turn it off when your design system styles everything.
  • nonce goes 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.

HookWhat it gives
useSurfaceA surface as this person has it: a list's visible and overflow actions, a choice's value, a collection, or a page
useStandardA surface as the application ships it
useCommandask(text), with its pending state, result and error
usePlanplan(), with its pending state
useActionRuns one action from the application's own control, counted as use
usePerformRuns any action; writes wait for the person's yes
useConfirmationThe run waiting for a yes, with confirm and cancel, for a confirmation of your own
useQuery, useQueriesQuery results, shared and cached
useUitiveRouterConnects your router: location in, links out
useLocationWhere the person is, as the router last reported it
useRankedEvery action, ranked by use, for a command palette
useViewWhether the person sees their own interface or the standard one
useLatest, usePendingThe latest adaptation, and changes waiting for a safe moment
useUserPagesThe pages the person made
useSnapshotEverything the client holds, for panels; it changes with every use
useLifecycleWhat 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.

tsx
export function OrdersPage() {
  const value = useSurface(uitive, 'orders');
  return <Page value={value} blocks={{}} regions={{ orders: OrdersList }} />;
}
  • regions gives each region its component: usually the existing page.
  • blocks gives each of the application's own blocks its component, typed by the block's props with BlockComponents: see Pages.
  • context is the page's context value, and current the row it is about; by default, the row the location names. Blocks whose queries name $current show as loading until the row is known.
  • Each block sits in a wrapper with data-block and data-element attributes, and the page and its sections carry data-layout, for styling; className replaces the page's uitive-page class.

Routers

Tell the client where the person is on every route change, and let it follow links through your router. With React Router:

tsx
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:

tsx
// 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>
  ),
});
BlockParts
page, section, tabsTitle (a page's own heading), Section (a container and its title), Tabs
tableTable, Value for each cell, Button for row actions
list, timelineList, Badge
detailGrid, Text
metricStat, Value
chartChart
boardGrid, Card, List
form, actionsStack, Field, Button, Text
note, linksCard, Text, Link
every blockStatus (empty, loading, error, partial data), Notice after a run
confirmations, run formsDialog, Field, Button, Value
  • Blocks have no container of their own: map Section to your card or panel when tables and lists should sit inside one.
  • The default Dialog is a native modal <dialog>: it takes focus when it opens, keeps it inside, closes on Escape and gives focus back when it closes. A Dialog of your own should do the same.
  • The default Tabs move with the arrow keys, Home and End, with one tab stop for the list. The default Chart never 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.currency says which currency a point is in.
  • Notice says 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.
  • values changes how one kind of value shows everywhere, such as money, 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-badge and --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; docked puts 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. collapsed starts the debug panel folded.
  • className and these flags are set on the element directly, so React 18 and 19 render them alike.
  • Bundlers leave UitiveDebug and 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-radius and --uitive-font, with ::part(content) and ::part(heading) for more.