Scopes can define a special method called getState(). It's just a regular method but it has special integration in the Store: it powers useAuiState, AuiIf as well as the subscribe API.

Defining state#

First, register getState and its return type in ScopeRegistry:

import "@assistant-ui/store";

declare module "@assistant-ui/store" {
  interface ScopeRegistry {
    counter: {
      methods: {
        getState: () => { count: number; step: number };
        increment: () => void;
        setStep: (n: number) => void;
      };
    };
  }
}

The return type of getState defines the shape of s.counter in useAuiState((s) => s.counter.count). A scope doesn't have to define getState(): if it only has methods and no readable state, that's fine.

Then implement getState() in the resource. It should return a memoized object built from the resource's internal state:

import { resource } from "@assistant-ui/tap";
import { useState, useMemo } from "react";
import type { ClientOutput } from "@assistant-ui/store";

const useCounterResource = (): ClientOutput<"counter"> => {
  const [count, setCount] = useState(0);
  const [step, setStep] = useState(1);

  const state = useMemo(() => ({ count, step }), [count, step]);

  return {
    getState: () => state,
    increment: () => setCount((c) => c + step),
    setStep: (n: number) => setStep(n),
  };
};

const CounterResource = resource(useCounterResource);

Use useMemo to create the state object. This ensures a stable reference when nothing changed, since Store uses reference equality to detect updates. The useState values in the dependency array trigger a resource re-render when they change, which is when Store checks for new state.

useAuiState#

useAuiState subscribes to state. You must pass a selector function which selects a slice of the store to subscribe to. The component re-renders only when the selected value changes.

const count = useAuiState((s) => s.counter.count);

The selector function receives a state object where each key corresponds to a scope. s.counter is the return value of the counter's getState().

// ❌ Avoid: re-renders on any counter state change
const { count } = useAuiState((s) => s.counter);

// ✅ Prefer: re-renders only when count changes
const count = useAuiState((s) => s.counter.count);

Selecting from multiple scopes#

The most common pitfall with useAuiState is returning a new object from the selector:

// ❌ Infinite re-render: creates a new object every time
const summary = useAuiState((s) => ({
  count: s.counter.count,
  name: s.user.name,
}));

useAuiState compares the selector's return value by reference (Object.is). An object literal like { count, name } creates a new reference every time the selector runs, so Store thinks the value changed, re-renders the component, which runs the selector again (infinite loop).

The fix is simple: use a separate useAuiState call for each value.

const count = useAuiState((s) => s.counter.count);
const name = useAuiState((s) => s.user.name);

This is also more precise: the component only re-renders when the specific value it uses changes, not when any of the selected scopes change.

Checking if a scope exists#

Accessing s.counter in a selector throws if the counter scope hasn't been provided. To read state from a scope that may not exist, use s.optional — an unavailable scope resolves to undefined instead of throwing:

const count = useAuiState((s) => s.optional.counter?.count);

To branch on availability outside a selector, use the client's mirror of this view: useAui().optional.counter is the bound accessor when available and undefined when not.

AuiIf#

AuiIf renders its children only when a state condition is true:

<AuiIf condition={(s) => s.counter.count > 0}>
  <ResetButton />
</AuiIf>

It uses useAuiState internally, so it re-evaluates only when the selected values change.

Under the hood: subscribe + getState#

Both useAuiState and AuiIf are built on two primitives available on the store:

• aui.subscribe(callback): calls callback whenever any scope's state changes
• aui.counter.getState(): returns the current state snapshot

Together, they form the standard useSyncExternalStore pattern. You can use them directly for non-React integrations or when you need imperative access:

const aui = useAui();

// imperative read
const count = aui.counter.getState().count;

// manual subscription
const unsub = aui.subscribe(() => {
  console.log("new count:", aui.counter.getState().count);
});