# State Rendering

> Render your agent's state with custom UI components in real-time.

## What is this? [#what-is-this]

State rendering lets you build UI that reflects your agent's state in real-time. As your agent progresses through nodes and emits state updates, your frontend renders those changes, showing progress, drafts, or intermediate results.

## When should I use this? [#when-should-i-use-this]

Use state rendering when you want to:

- Show real-time progress (e.g. "Researching... 2/5 complete")
- Display drafts that update as the agent works
- Build dashboards that reflect agent state
- Render structured output outside of the chat

## How it works in code [#how-it-works-in-code]

On the frontend, subscribe to the agent's state. Each time the backend forwards a fresh value, your component re-renders with the latest partial output. `useAgent` returns an `agent` ref; read `agent.value?.state` in script or let templates unwrap the ref. Keep the provider in an ancestor SFC.

```vue title="src/components/ResearchProgress.vue"
<script setup lang="ts">
import { computed } from "vue";
import { useAgent, UseAgentUpdate } from "@copilotkit/vue/v2";

type ResearchState = { status?: string; draft?: string; completed?: number; total?: number };

const { agent } = useAgent({
  agentId: "researcher",
  updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged],
});

const state = computed(() => (agent.value?.state ?? {}) as ResearchState);
</script>

<template>
  <section aria-live="polite">
    <p>{{ state.status ?? "Idle" }}</p>
    <progress :value="state.completed ?? 0" :max="state.total ?? 1" />
    <article v-if="state.draft">{{ state.draft }}</article>
  </section>
</template>
```

```vue title="src/App.vue"
<script setup lang="ts">
import { CopilotChat, CopilotKitProvider } from "@copilotkit/vue/v2";
import ResearchProgress from "./components/ResearchProgress.vue";
</script>

<template>
  <CopilotKitProvider runtime-url="/api/copilotkit">
    <ResearchProgress />
    <CopilotChat agent-id="researcher" />
  </CopilotKitProvider>
</template>
```

On the backend, a state-streaming mapping forwards a tool argument into a state key while the model writes it. Some frameworks provide that as middleware. Direct SDK adapters can emit `STATE_SNAPSHOT` events from their streaming loop. Either way, the UI can watch the answer assemble token-by-token rather than appearing in one burst between checkpoints.

<Steps>
  <Step>
    ### Install the CopilotKit LangGraph SDK

    ```bash
    npm install @copilotkit/sdk-js
    ```

  </Step>
  <Step>
    ### Map generated content into shared state while it streams

    Extend your graph state with `CopilotKitStateAnnotation`, then call
    `copilotkitCustomizeConfig` with an `emitIntermediateState` mapping. This
    forwards the `write_document.document` tool argument into `state.document`
    while the model is still generating it.

~~~~typescript title="shared-state-streaming.ts"
  const streamingConfig = copilotkitCustomizeConfig(config, {
    emitIntermediateState: [
      {
        stateKey: "document",
        tool: "write_document",
        toolArgument: "document",
      },
    ],
  });

  const response = await modelWithTools.invoke(
    [systemMessage, ...state.messages],
    streamingConfig,
  );
~~~~

    To push progress from your own code instead of a tool call, call
    `copilotkitEmitState` with the state you want the UI to show:

    ```ts title="agent-js/src/agent.ts"
    import { copilotkitEmitState } from "@copilotkit/sdk-js/langgraph";

    for (const step of steps) {
        state.observed_steps = [...(state.observed_steps ?? []), step];
        await copilotkitEmitState(config, state);
    }
    ```

    Streamed values are previews. When the node finishes, the state it
    returns replaces them, so return every key you want to keep, or the UI
    loses the streamed value.

  </Step>
</Steps>

```typescript title="src/agent/shared-state-streaming.ts"
  const streamingConfig = copilotkitCustomizeConfig(config, {
    emitIntermediateState: [
      {
        stateKey: "document",
        tool: "write_document",
        toolArgument: "document",
      },
    ],
  });

  const response = await modelWithTools.invoke(
    [systemMessage, ...state.messages],
    streamingConfig,
  );
```

Ask the researcher agent to write a report. The status line and the progress bar change while the agent runs, and the draft text grows as the tokens arrive.

Treat agent state as untrusted external data. Validate it before using it for privileged actions, and avoid putting secrets in state that is streamed to the browser.

<IntegrationGrid
  path="generative-ui/state-rendering"
  exclude={["agno", "agent-spec"]}
/>
