---
title: "Add actions and state bindings to atoms"
slug: "add-actions-and-state-bindings-to-atoms"
abstract: "Define atom actions, emit events from React renderers, and connect editable props to component-layout state."
---
# Add actions and state bindings to atoms

Actions let an atom respond to events, such as a button press or form submission. State bindings let a renderer read layout state and write changes back from inputs.

Before you begin, connect a catalog and registry to `SitecoreProvider` through `atomsConfig`. See [Get started with atoms](https://doc.sitecore.com/sai/en/developers/content-sdk/20/get-started-with-atoms.html).

> [!important]
> The features described in this topic are available only to customers enrolled in [Early Access](https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=hAFwkRTDyU27fqQR30VqHj_zY3lpy3dGhZKklnheMCxURUpHTkhSSzI4QkhCUFMzSDM2M1ZGRkYwMi4u) and are intended for testing in non-production environments.

## Define an action and emit an event

Define the action in the catalog, including a parameter schema when it takes arguments, and register a handler with the same name. The renderer calls `emit` with the event name that the component layout binds to an action.

<!-- Note for later: the source-described async handler and its three arguments match the delegated defineRegistry declarations and runtime in @json-render/react 0.20.0. The SDK's separate AtomActionHandler alias takes only params. Also, atoms.md describes a void | Promise<void> return, while the delegated declaration requires Promise<void>. This draft uses the source's async example and does not promise synchronous handler support. Resolve these type inconsistencies before publication. -->

In `src/atoms/index.tsx`, define a button and a `submit` action:

```tsx
import { z } from 'zod';
import {
  defineAtomsCatalog,
  defineAtomsRegistry,
} from '@sitecore-content-sdk/nextjs/atoms';

type LayoutState = Record<string, unknown>;
type SetLayoutState = (
  updater: (previous: LayoutState) => LayoutState
) => void;

export const catalog = defineAtomsCatalog({
  components: {
    Button: {
      props: z.object({ label: z.string() }),
      description: 'A button',
    },
  },
  actions: {
    submit: {
      params: z.object({ formId: z.string() }),
      description: 'Submit a form',
    },
  },
});

export const registry = defineAtomsRegistry(catalog, {
  components: {
    Button: ({ props, emit }) => (
      <button type="button" onClick={() => emit('press')}>
        {props.label}
      </button>
    ),
  },
  actions: {
    submit: async (
      params: { formId: string },
      setState: SetLayoutState
    ) => {
      await fetch('/api/submit', {
        method: 'POST',
        body: JSON.stringify(params),
      });
      setState((previous) => ({ ...previous, submitted: true }));
    },
  },
});
```

The asynchronous handler can use the following arguments:

| Argument | Purpose |
| --- | --- |
| `params` | Arguments from the action binding, with state references already resolved. |
| `setState` | Updates component-layout state. Pass an updater that receives the previous state and returns the next state. |
| `state` | State snapshot from when the action started. |

An action definition accepts these fields:

| Field | Required | Purpose |
| --- | --- | --- |
| `params` | No | Zod schema for the action arguments. Omit it when the action takes none. |
| `description` | No | Describes what the action does. |
| `legacy` | No | When `true`, Design Studio can leave the action out of new generations. Existing usages still run. Defaults to `false`. |

Pass the whole return value of `defineAtomsRegistry` as `atomsConfig.registry`. Catalog action names and registry handler names must match. A catalog action without a handler doesn't run.

### Connect the emitted event to the layout

The button emits `press`; emitting the event alone doesn't define which action runs. The component layout element's `on` field maps event names, such as `press` or `submit`, to action bindings. The binding supplies the action arguments.

The element's `on` map is layout data. The renderer receives a separate `on` function: `on('press')` returns `{ emit, shouldPreventDefault, bound }` when the renderer needs to inspect whether the event has a binding.

<!-- Note for later: atoms.md does not provide the JSON syntax of an action binding. Add a full end-to-end example connecting the Button element's press event to submit with formId only after the source supplies that syntax. The sample above defines and emits the event but is not a complete event-to-action binding example. Do not infer binding syntax from application code. -->

## Use built-in actions

The runtime provides these actions without catalog entries or registry handlers:

| Action | Purpose |
| --- | --- |
| `setState` | Write a value at a state path. |
| `pushState` | Append an item to an array in state. |
| `removeState` | Remove an array item by index. |
| `validateForm` | Validate registered fields and write the result to state. |

## Enable navigation after an action

Provide `navigate` on `atomsConfig` when action bindings should change routes. The runtime calls it when a binding sets `onSuccess.navigate` to a path. Navigation is separate from the handler arguments.

The starters pass the Next.js router's `push` function:

```tsx
atomsConfig={{
  catalog,
  registry,
  navigate: router.push,
}}
```

Add this property to the existing provider configuration. For the provider setup, see [Get started with atoms](https://doc.sitecore.com/sai/en/developers/content-sdk/20/get-started-with-atoms.html#connect-the-provider).

## Read and update layout state

The component layout's `state` field defines its initial state. At render time, the SDK sets `state.fields` from the Sitecore rendering's fields and `state.params` from its parameters.

An element's `props` can contain literal values, state reads, or two-way bindings:

| Prop value | Purpose |
| --- | --- |
| `$state`, `$item`, `$index` | Read values from state or the current repeated item and its index. |
| `$bindState`, `$bindItem` | Bind a prop for reading and writing state. |

For a bound prop, the renderer's `bindings` map contains the prop name and its state path. The map is present when at least one prop is bound.

Use `useBoundProp` to read a prop and write input changes to its bound path:

```tsx
import { useBoundProp } from '@sitecore-content-sdk/nextjs/atoms';

type InputRendererProps = {
  props: { value?: string };
  bindings?: Record<string, string>;
};

const Input = ({ props, bindings }: InputRendererProps) => {
  const [value, setValue] = useBoundProp<string>(props.value, bindings?.value);
  return (
    <input value={value ?? ''} onChange={(event) => setValue(event.target.value)} />
  );
};
```

Register this renderer under the matching catalog component name. `useBoundProp` returns the current value and a setter. When the prop has no binding, the setter does nothing.

## Keep layout behavior on the element

The layout places these fields next to `props`:

| Element field | Purpose |
| --- | --- |
| `on` | Map of event name to an action binding. |
| `visible` | Condition that controls whether the element renders. |
| `repeat` | Renders the element's children once per item in a state array. |
| `watch` | Map of state path to an action binding. The action runs when that value changes, after the first render. |

The runtime applies these fields before the atom component runs. For the document structure, see [Atoms in Content SDK apps](https://doc.sitecore.com/sai/en/developers/content-sdk/20/atoms-in-content-sdk-apps.html#component-layouts).

The lock file checks component definitions, not action definitions. An action-only edit doesn't fail `atoms validate`. After an intentional change to a component definition, run `npm run sitecore-tools:atoms:update` and commit the lock file. For missing events or state updates, see [Troubleshoot atoms](https://doc.sitecore.com/sai/en/developers/content-sdk/20/troubleshoot-atoms.html#an-action-doesnt-run-or-an-input-doesnt-update-state).
