VoltroDocumentation

React hooks — overview

The client-side hook surface, grouped by purpose.

The web side of a Voltro app talks to API apps through React hooks. Data hooks are keyed by API name and RPC tag; routing hooks are provided by @voltro/web.

Data Hooks

Hook Purpose
useSubscription Subscribe to a reactive query (*.query.ts).
useMutation Run an atomic write (*.mutation.ts).
useAction Run a unary non-transactional action (*.action.ts).
useWorkflow Start, cancel, resume, or signal a durable workflow (*.workflow.tsx).
useWorkflowSignal Focused signal sender, for approval buttons that don't also start workflows.
useWorkflowUpdate Focused tracked update — waits for the workflow handler's result.
useWorkflowRun Subscribe to one workflow run's reactive status row.
useWorkflowRuns Subscribe to a bounded/filterable workflow run list.
useWorkflowRunSteps Subscribe to one run's checkpointed step timeline.
useWorkflowRunEvents Subscribe to one run's lifecycle/timer/signal event timeline.
useWorkflowDomainEvents Subscribe to the domain events a workflow emitted (the business-event timeline).
useWorkflowEventDeliveries Subscribe to delivery attempts/outcomes for those emitted events.
useWorkflowRunState Aggregates run + steps + events into one { status, currentStep, waitingFor, … } plus cancel/resume/signal/update.
useAgentStream Consume a one-shot element stream (*.stream.ts).
useAgent Convenience wrapper for transient AI streams.

Routing Hooks

Hook Purpose
useLocation Current pathname and route state.
useParams URL params from [name] segments.
useNavigate Programmatic navigation.
usePrefetch Trigger loader-data prefetch.
useLoaderData Page loader output.

Server / Context Hooks

Hook Purpose
useServerRequest Request snapshot during SSR and hydration-sensitive client code.

Schema-driven UI Hooks

The headless primitives that derive UI from a descriptor's Schema. Reach for these before hand-rolling a form, a table, or a picker — full guide in Schema-driven UI.

Hook Purpose
useFormBinding Bind a form to a MUTATION — fields + validation from its input Schema; a server ValidationError({ field }) routes to that field.
useDataTable Bind a table to a QUERY — live rows, columns derived from the output Schema, sort/filter/pagination.
useQueryFilters Filter controls derived from a query's INPUT Schema (the read-side mirror of a form).
useQueryField Query-bound picker — a debounced search term drives a live subscription.
useFormSkeleton / useTableSkeleton Placeholders shaped like the REAL data, from the same Schema.
useAsyncValidation Live server-side validation (uniqueness, cross-row) over a query binding.
useDebounced Debounce a value (search, filter, validation input).
useRecord One live record from a "get" query, normalized (array → first row).

Files, Permissions, and Client Utilities

Hook Purpose
useUpload File upload with progress + cancel, on every storage provider. Not base64 → action.
useCan Scope/RBAC UI gate, over <PermissionProvider>. Lives in @voltro/client — scopes are a framework concept, so gating a button needs no rbac dependency.
useCanAny OR variant of useCan — true when the subject holds AT LEAST ONE of the required scopes.
usePermissions / <PermissionProvider> The current subject's scope set, fed once from your session query — the source useCan reads. Gates UI on the SAME scope strings the server checks.
useResourceCan / useResourceCans Per-RESOURCE (ReBAC) gate, reactive — one resource or many in a single subscription.
useDerived Dependency-tracked derived value from reactive sources. Replaces hand-maintained useMemo dep arrays.
useWindowedSubscription Subscribe to the VISIBLE window of a huge list, not the whole table.
useOutbox Queue mutations offline, replay in order on reconnect.
useUndoLog / useUndo Client controller for the server-persisted undo stack.
usePreview Mutation dry-run — run the real handler in a rolled-back transaction.
useProvenance "Why is this value here?" — lineage lookup for a field.
useOnRpcError / reportClientError Subscribe to the rpc error bus; report a client error to the server.
useTracking Fire mount/unmount + interaction tracking events.
useCapabilityManifest The api's capability manifest (procedures + tables + schemas), fetched once.
useRefreshSubscriptions Force-refresh live subscriptions (e.g. after an out-of-band change).

AI Hooks

Hook Purpose
useAgentChat Full chat surface over an *.agent.tsx (messages + send + streaming).
useResumableAgentStream Agent stream that survives reload/reconnect.
useDataCopilot Bind a data-copilot action by api name + tag.