@studio-vaai/react-headless

React hooks and a provider for the studio vaai virtual try-on flow — the headless layer: all behaviour, no UI.

Want prebuilt, styled UI instead? Use @studio-vaai/react-components.

Install

npm install @studio-vaai/react-headless @studio-vaai/js-client

Peer dependencies: react and react-dom (^18 or ^19).

Import this package only in application code — its lower layers stay transitive. Two optional subpath entrypoints re-export them if you need direct access (no React in either):

• @studio-vaai/react-headless/client — the HTTP contract and createClient stub.
• @studio-vaai/react-headless/machine — the XState machines.

Quick start

1. Obtain a StudioVaaiClient (e.g. createFetchStudioVaaiClient from @studio-vaai/js-client).
2. Wrap your tree with StudioVaaiProvider, passing client and input.
3. In children, call useStudioVaaiActor().

"use client";

import {
  StudioVaaiProvider,
  useStudioVaaiActor,
  type DefaultRootInput,
  type StudioVaaiClient,
} from "@studio-vaai/react-headless";

function App({ client }: { client: StudioVaaiClient }) {
  const input: Omit<DefaultRootInput, "client"> = {
    productId: "...",
    selection: { variantSlug: "", attributes: {} },
  };

  return (
    <StudioVaaiProvider client={client} input={input}>
      <Step />
    </StudioVaaiProvider>
  );
}

function Step() {
  const { state, dispatch } = useStudioVaaiActor();
  return <pre>{JSON.stringify(state.value, null, 2)}</pre>;
}

useStudioVaaiActor() returns:

| Field | Role | | -------------- | ------------------------------------------------------------------------ | | state | Current snapshot of the flow — which step you're on, plus context data. | | dispatch | Send a typed event (e.g. { type: "…" }) to advance or branch the flow. | | actor | The underlying actor, for advanced use and debugging. |

Use useStudioVaaiSelector when you only need a slice of state, to limit re-renders.

Custom root machine

createStudioVaaiContext(yourMachine) returns a StudioVaaiProvider and hooks typed for your own machine. The default export is built on defaultRootMachine, which is also re-exported for composition.

Errors

| Error | When | | ----------------------------------------- | ------------------------------------------------------------------------ | | StudioVaaiProviderError | A hook is used outside StudioVaaiProvider. | | StudioVaaiClientNotImplementedError | createClient() was called without a transport. | | ApiFailureError | An actor threw after a failed API result; failure holds the API error. |

Next.js / SSR

Mount the provider and hooks under a "use client" boundary. This library does not assume window in its module scope.

License

MIT