Documents
README
README
Type
External
Status
Published
Created
Mar 17, 2026
Updated
Mar 17, 2026

@assistant-ui/store#

Tap-based state management with React Context integration.

Quick Start#

import { resource, tapState } from "@assistant-ui/tap";
import { useAui, useAuiState, AuiProvider, type ClientOutput } from "@assistant-ui/store";

// 1. Define client type
declare module "@assistant-ui/store" {
  interface ScopeRegistry {
    counter: { methods: { getState: () => { count: number }; increment: () => void } };
  }
}

// 2. Create resource
const CounterClient = resource((): ClientOutput<"counter"> => {
  const [state, setState] = tapState({ count: 0 });
  return { getState: () => state, increment: () => setState({ count: state.count + 1 }) };
});

// 3. Use in React
function App() {
  const aui = useAui({ counter: CounterClient() });
  return <AuiProvider value={aui}><Counter /></AuiProvider>;
}

function Counter() {
  const count = useAuiState((s) => s.counter.count);
  const aui = useAui();
  return <button onClick={() => aui.counter().increment()}>{count}</button>;
}

Concepts#

Clients: Named state containers registered via module augmentation.

declare module "@assistant-ui/store" {
  interface ScopeRegistry {
    myClient: {
      methods: MyMethods; // must include getState(): MyState
      meta?: { source: "parent"; query: { id: string } };
      events?: { "myClient.updated": { id: string } };
    };
  }
}

Derived Clients: Access nested clients from parents.

useAui({
  item: Derived({ source: "list", query: { index: 0 }, get: (aui) => aui.list().item({ index: 0 }) }),
});

Events:

const emit = tapAssistantEmit();
emit("myClient.updated", { id: "123" });

useAuiEvent("myClient.updated", (p) => console.log(p.id));

API#

Hook/ComponentDescription
useAui()Get client from context
useAui(clients)Create/extend client
useAuiState(selector)Subscribe to state
useAuiEvent(event, cb)Subscribe to events
AuiProviderProvide client to tree
AuiIfConditional rendering
Tap UtilityDescription
tapAssistantClientRef()Access client ref in resources
tapAssistantEmit()Emit events from resources
tapClientResource(element)Wrap resource for event scoping (1:1 mappings)
tapClientLookup(map, fn, deps)Lookup by {index} or {key}
tapClientList(config)Dynamic list with add/remove
attachTransformScopes(resource, fn)Attach scope transform
TypeDescription
ClientOutput<K>Resource return type (methods object)
ScopeRegistryModule augmentation interface
AssistantClientFull client type