React hooks

@stndrds/react wraps the REST API in TanStack Query hooks. Every query hook returns a standard UseQueryResult (data, isLoading, error, refetch, …). Every mutation hook returns a UseMutationResult (mutate, mutateAsync, isPending, …). Everything TanStack Query offers works here.

pnpm add @stndrds/react @tanstack/react-query

Provider setup

StandardsAppProvider from @stndrds/ui already wires up SchemaClientProvider for you — see Client setup. The config below is for headless integrations.

Wrap the app in SchemaClientProvider. Auth is injected through headers or a custom fetch — there is no apiKey config field.

import { SchemaClientProvider } from "@stndrds/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <SchemaClientProvider
        queryClient={queryClient} // share the app's QueryClient
        config={{
          baseUrl: "https://api.standards.new",
          apiPrefix: "/v1",
          headers: { Authorization: `Bearer ${accessToken}` },
        }}
      >
        {children}
      </SchemaClientProvider>
    </QueryClientProvider>
  );
}

SchemaClientConfig options:

The provider also accepts renderFileViewer (renders file previews), hooks (client record lifecycle hooks built with recordHooks()), and translations (a French bundle ships in @stndrds/react/locales/fr).

For imperative access, useSchemaClient() returns the underlying SchemaClient.

Fetching records

Hooks are generic over the record's values shape — pair them with ExtractRecord for end-to-end typing.

import { useRecord, useRecords } from "@stndrds/react";

function ContactList() {
  const { data, isLoading } = useRecords<Contact>("contacts", {
    limit: 50,
    sorts: [{ attribute: "lastName", direction: "asc" }],
    filters: {
      combinator: "and",
      rules: [{ attribute: "status", operator: "is", value: "active" }],
    },
  });

  if (isLoading) return <Spinner />;
  return data?.data.map((record) => <li key={record.id}>{record.label}</li>);
}

function ContactDetail({ id }: { id: string }) {
  const { data: contact } = useRecord<Contact>("contacts", id);
  // ...
}

Records come back as ObjectRecord<TValues>:

{
  id: string;
  objectId: string;
  label: string; // rendered labelExpression
  values: TValues; // your attributes
  createdAt: Date;
  updatedAt: Date;
}

createdAt and updatedAt are typed as Date but arrive as ISO strings over JSON — parse them before calling Date methods.

There is no draft/complete field on the record. CreateRecordOptions.allowDraft lets a create skip required-field validation, and isRecordComplete() checks completeness on demand — draft state is never stored on the record itself.

Filtering, sorting, and pagination

All list hooks accept the same ListParams:

{
  limit?: number;
  offset?: number;
  countMode?: "none" | "estimated" | "exact";
  sorts?: { attribute: string; direction: "asc" | "desc" }[];
  filters?: FilterState;
  fields?: string[]; // reference attributes to hydrate
}

FilterState combines rules with and/or:

{
  combinator: "and" | "or";
  rules: {
    attribute: string;
    operator: FilterOperator;
    value: FilterValue; // null for is_empty / is_not_empty
    property?: string;      // filter on a qualified relation property
    quantifier?: "any" | "none";
  }[];
}

The valid operators depend on the attribute's type — see the operator table. A rule's value can also be resolved at query time rather than fixed: see dynamic values.

Mutating records

Each mutation hook takes (objectName, options?) where options are { onSuccess, onError, onSettled }. All mutations update the cache optimistically.

import { useCreateRecord, useUpdateRecord, useDeleteRecord } from "@stndrds/react";

const { mutate: createContact, isPending } = useCreateRecord<ContactInput>("contacts", {
  onSuccess: (record) => toast.success(`Created ${record.label}`),
});

createContact({ data: { firstName: "Ada", lastName: "Lovelace" } });

const { mutate: updateContact } = useUpdateRecord<Contact>("contacts");
updateContact({ recordId: id, data: { email: "[email protected]" } });

const { mutate: deleteContact } = useDeleteRecord("contacts");
deleteContact(id); // soft delete — restorable from trash

Schema hooks

Read (and administer) the schema itself:

Admin mutations exist for all of these (useCreateObject, useUpdateObject, useDeleteObject, useAddAttribute, useUpdateAttribute, useDeleteAttribute, useCreateView, useUpdateView, useSetDefaultView, …) with the same { onSuccess, onError, onSettled } options.

Documents and files

Folder navigation hooks (useFolderChildren, useFolderAncestors, useCreateFolder, useMoveDocument, …) cover the drive UI.

Users, permissions, and the rest

• Current user — useMyProfile(), useUpdateMyProfile(), useMyPermissions().
• Access control — useCanAccess(objectName, action) returns boolean | undefined; useObjectPermissions, useRoles and role mutations for admin.
• Feature flags — useFeatureFlag(name), useFeatureFlagValue(name, default), useTier(flagName, defaultTier), and the <Feature> gate component.
• Realtime — useLiveSubscription for live record updates, notifications via useNotifications / useNotificationCounts. Headless apps wrap with RealtimeProvider first; the app shell already includes it.
• Forms — useForms, useFormByName, useCreateFormSubmission, useSaveFormStep, useAdvanceFormStep.
• Agents — useAgentDefinitions, useAgentSessions, useRunAgent, useAgentChatSession; create and update mutations accept visibility.

Agent chat sessions

useAgentChatSession manages an interactive agent conversation with message history and real-time streaming. Its error field surfaces failures across the full session lifecycle:

• Message send errors — when sendMessage fails to submit new input.
• Session creation errors — when creating a new session fails.
• Session cancellation errors — when stopping an in-progress session fails.
• Message load errors — when fetching the session's existing conversation history fails on mount. This distinguishes a session whose history could not be loaded from one that genuinely has no messages yet — both leave the messages list empty, but only a load failure sets error.

error resolves in a fixed order, not by recency: send failure, then first-message failure, then session creation, then cancellation, and finally the load failure. The interactive failures come first because they answer a gesture the user just made; a load failure is ambient, so it only shows when nothing more immediate is pending.

Cache invalidation

The package exports query-key factories so you can invalidate exactly the queries you touched when mutating outside the hooks:

import { documentsKeys, recordsKeys } from "@stndrds/react";

queryClient.invalidateQueries({
  queryKey: documentsKeys.recordDocuments(objectName, recordId),
});

Available factories: recordsKeys, objectsKeys, attributesKeys, viewsKeys, documentsKeys, filesKeys, usersKeys, permissionsKeys, notificationKeys, formsKeys, agentKeys, and more.

Error handling

API errors are instances of SchemaApiError, which exposes .status and .details — every hook surfaces them through its error field.