# useGenerativeUIState

> Give generated components live app state, such as the cart, without sending it to the model

## Overview [#overview]

A generated `ProductCard` must show how many of the product are in the cart. The agent does not know that number, and it must not guess. `useGenerativeUIState` gives one key of the declared app state its value. The props that read this key get the value. The model does not see it.

<Callout type="warn">
  Generative UI is experimental. Call `useGenerativeUIState` in `setup()` (or
  `<script setup>`) of a component under a
  [`CopilotKitProvider`](/reference/vue/components/CopilotKitProvider) that has
  a `generativeUI` config. Outside such a provider, the composable throws an
  error.
</Callout>

For a full walkthrough, see [State and actions](/generative-ui/components/state-and-actions).

## Import [#import]

```ts
import { useGenerativeUIState } from "@copilotkit/vue/v2/generative-ui";
```

## Signature [#signature]

```ts
import type { MaybeRefOrGetter } from "vue";

useGenerativeUIState<UI, Key>(
  ui: UI,
  key: Key,
  value: MaybeRefOrGetter<StateInput<UI, Key>>,
): void;
```

`StateInput<UI, Key>` is the input type of the schema of `key`. It is not exported. Let TypeScript infer it from `ui` and `key`.

## Parameters [#parameters]

<PropertyReference name="ui" type="GenerativeUI" required>
  The object from `createGenerativeUI`. It gives `key` and `value` their types. Pass the same object that you give the provider as `generativeUI.ui`.
</PropertyReference>

<PropertyReference name="key" type="string" required>
  A top-level key of the `state` that you declare in `createGenerativeUI({ state })`.
</PropertyReference>

<PropertyReference name="value" type="MaybeRefOrGetter<StateInput<UI, Key>>" required>
  The value of the key. Pass a plain value, a `ref`, or a getter. The value must fit the schema of the key.
</PropertyReference>

## Return value [#return-value]

None. The composable writes the value to the provider.

## Example [#example]

`shopUI` declares the key in its state:

```ts title="shop-ui.ts"
const cartSchema = z.object({
  items: z.array(z.object({ productId: z.string(), quantity: z.number() })),
});

export const shopUI = createGenerativeUI({
  id: "acme/shop@1",
  state: { cart: cartSchema },
  components: {
    /* ... */
  },
});
```

Give the key its value from a component:

```vue title="CartState.vue"
<script setup lang="ts">
import { useGenerativeUIState } from "@copilotkit/vue/v2/generative-ui";
import { useCartStore } from "./cart-store";
import { shopUI } from "./shop-ui";

const cart = useCartStore();

useGenerativeUIState(shopUI, "cart", () => ({ items: cart.items }));
</script>

<template>
  <slot />
</template>
```

## Behavior [#behavior]

- The key is set at once. It is set again when the value changes. Values are compared as JSON.
- The value goes through the schema of the key. Schema defaults and transforms apply.
- An invalid value is not stored. The props that read the key show their fallback. In development, an error is logged.
- The key is removed when the effect scope is disposed, for example when the component unmounts.
- The model does not see the state. To let the agent answer questions about it, also give the data with [`useAgentContext`](/reference/vue/hooks/useAgentContext).

## Related [#related]

- [`useGenerativeUIFunction`](/reference/vue/hooks/useGenerativeUIFunction) - run your code when generated UI calls a function
- [`GenerativeUISurface`](/reference/vue/components/GenerativeUISurface) - mark an area of your page for generated UI
- [`CopilotKitProvider`](/reference/vue/components/CopilotKitProvider) - give the provider the `generativeUI` config
