Resources

A resource is a self-contained unit of reactive state and logic — like a React component, but without UI.

Defining a resource

You define a resource with the resource function.

import { resource, tapState } from "@assistant-ui/tap";

const Counter = resource(({ initialValue = 0 }: { initialValue?: number }) => {
  const [count, setCount] = tapState(initialValue);

  return {
    count,
    increment: () => setCount((c) => c + 1),
  };
});

resource() returns a factory function. Calling the factory creates a ResourceElement — a lightweight description of what to render, not an active instance yet.

ResourceElements

A ResourceElement is a simple { type, props } object — the same idea as a React JSX element ({ type, props } under the hood), but without JSX syntax.

const element = Counter({ initialValue: 10 });
// { type: Counter, props: { initialValue: 10 } }

We deliberately avoided JSX for resource elements. In our testing, JSX confused users because it looked like UI code but wasn't rendering anything visible. Instead, we use a calling convention inspired by Flutter — ResourceName({ props }) — so that it reads like normal function calls.

Just like in React, a ResourceElement is inert. It doesn't do anything on its own — it's a description of what to render, not an active instance. See Instances for how to bring them to life.

Props

Resources can accept props, just like React components. In the example above, Counter takes an initialValue prop.

Props are passed to a resource instance by its owner — which can be another resource (via tapResource), a React component (via useResource), or imperative code (via createResourceRoot).

When a resource re-renders with new props, hooks like tapEffect and tapMemo can react to the changes through their dependency arrays.

Return value

Resources can return a value. This is how you expose state and methods to the outside world. Unlike React components which return JSX nodes, resources can return any JavaScript value — objects, arrays, numbers, strings, or anything else.

The return value is what you get when you read from an instance — directly from useResource in React, or via handle.getValue() with createResourceRoot.

Keys

You can attach a stable key to a ResourceElement with withKey. Keys are used to preserve identity when rendering lists with tapResources.

import { withKey } from "@assistant-ui/tap";

const element = withKey("my-counter", Counter({ initialValue: 10 }));
// { type: Counter, props: { initialValue: 10 }, key: "my-counter" }

Keys work the same way as React's key prop — when the key stays the same, the resource keeps its state. When the key changes, the resource is unmounted and a fresh one is created.

Instances

A ResourceElement is just a description — it doesn't do anything on its own. To bring it to life, you create an instance. There are two ways to do this:

useResource

Use useResource inside React components. The resource's lifecycle is tied to the component — it mounts when the component mounts and unmounts when the component unmounts.

import { useResource } from "@assistant-ui/tap/react";

function CounterComponent() {
  const { count, increment } = useResource(Counter({ initialValue: 10 }));

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
}

The component re-renders whenever the resource's state changes.

createResourceRoot

Use createResourceRoot for imperative, framework-agnostic usage.

import { createResourceRoot } from "@assistant-ui/tap";

const root = createResourceRoot();
const handle = root.render(Counter({ initialValue: 10 }));

// read state
handle.getValue().count; // 10

// subscribe to changes
handle.subscribe(() => {
  console.log(handle.getValue().count);
});

// call methods
handle.getValue().increment();

// update props
root.render(Counter({ initialValue: 20 }));

// cleanup
root.unmount();