- Developer guides
Atoms in Content SDK apps
Atoms are the UI building blocks a Next.js app exposes to Sitecore Design Studio. Design Studio composes them into a component layout, and the app renders that layout with the React components you register.
The Pages Router, App Router, and App Router with Cache Components starters created using the CLI include atoms support.
The features described in this topic are available only to customers enrolled in Early Access and are intended for testing in non-production environments.
Catalog, registry, and lock file
Three parts work together to define, render, and validate atoms:
| Part | Purpose |
|---|---|
| Catalog | Defines the components and actions Design Studio can use, including prop schemas, descriptions, slots, and placement constraints. |
| Registry | Maps each catalog name to a React renderer or an action handler in your app. |
| Lock file | Stores a hash of each component definition. Validation compares the lock file with the catalog during dev and build. |
Use defineAtomsCatalog to define the catalog and defineAtomsRegistry to register the implementations. Import both from @sitecore-content-sdk/nextjs/atoms, and pass their return values to SitecoreProvider through atomsConfig.
Prop schemas use Zod. For props that authors edit as Sitecore fields, the SDK provides field-schema helpers, such as textFieldSchema and imageFieldSchema. These helpers define the field's data shape and attach the editor hints Design Studio uses.
An action is an operation the app runs when a component fires an event, such as submitting a form. Define the action in the catalog and its handler in the registry. Include a parameter schema when the action takes arguments.
The lock file, .sitecore/atoms.lock.json, records component definitions, not action definitions. Generate it with sitecore-tools project atoms update and commit it with your catalog changes. Use sitecore-tools project atoms validate to detect differences between the catalog and the lock file.
Atoms and Sitecore renderings
A React component registered in the component map renders as a Sitecore rendering in a placeholder. An atom is a named entry in the atoms catalog with a prop schema and a matching React renderer.
Register atoms through atomsConfig, separately from the component map. A component built from atoms uses the React implementations in the atoms registry to display its component layout.
On a published page, the SDK uses this rendering path when a Sitecore rendering's parameters include ComponentRef. It loads the referenced component layout and renders it with the atoms registry. The rendering's fields are available to the layout as state.fields, and its parameters are available as state.params.
If the reference is empty, the SDK can't load the layout, or atomsConfig is missing, the component doesn't render.
Component layouts
Design Studio authors the component layout as a document that describes the elements to render and their initial state:
| Field | Purpose |
|---|---|
name | Component name. |
root | Key of the root element. |
elements | Map of elements, keyed by ID. Each element's type identifies an atom in the catalog. |
state | Initial layout state. At render time, the SDK sets state.fields and state.params from the Sitecore rendering. |
Elements can include props, child elements, named slots, event bindings, and conditions that control visibility. An atom renderer receives the default slot's content as children and named-slot content through slots.
Preview and editing
During low-code preview, the app sends its catalog to Design Studio and renders updates to the component layout. The catalog describes the available atoms and actions, with Zod schemas converted to JSON Schema.
While the page is in editing mode, atoms are selectable in Design Studio and Pages. Published pages omit the editing markup.
To define your first atom and connect it to your app, see Get started with atoms.