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.
The features described in this topic are available only to customers enrolled in Early Access 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.
In src/atoms/index.tsx, define a button and a submit action:
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.
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:
Add this property to the existing provider configuration. For the provider setup, see Get started with atoms.
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:
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.
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.