Define an atoms catalog
An atoms catalog defines the components and actions Design Studio can use to build component layouts. Each component entry describes its props, slots, and placement. Register a matching React renderer to display it in your app.
For initial setup and provider configuration, 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 component props
In src/atoms/index.ts or src/atoms/index.tsx, export the result of defineAtomsCatalog as catalog. The CLI reads this named export.
The following catalog defines a button with a Sitecore text-field prop and a variant:
The Button key is the name shared by Design Studio and the registry. See Implement atom renderers and slots to register its renderer.
actions is required. Use actions: {} when the catalog has no actions. For action definitions and handlers, see Add actions and state bindings to atoms.
Catalog fields
| Field | Required | Purpose |
|---|---|---|
components | Yes | Component definitions, keyed by atom name. |
actions | Yes | Action definitions, keyed by action name. Use an empty object when there are none. |
version | No | Version of the whole catalog. Stored in the lock file and sent to Design Studio. See Validate and maintain an atoms catalog. |
stylingSolution | No | tailwind or inline-css. Defaults to inline-css. Tells Design Studio how the app is styled. |
stylingSolution doesn't configure CSS compilation. See Configure styling for atom-based components.
Component fields
| Field | Required | Purpose |
|---|---|---|
props | Yes | Zod object schema for the atom's props. |
description | No | Describes the atom for Design Studio generation. |
slots | No | Slot names the atom accepts. When omitted, Design Studio receives ['default']. |
allowedChildren | No | Atom names that can be placed in this atom's slots. Sent to Design Studio with the catalog. |
allowedParents | No | Atom names this atom can be placed inside. |
example | No | Sample prop values sent to Design Studio. |
version | No | Component version, checked separately from the definition hash. See Validate and maintain an atoms catalog. |
legacy | No | When true, Design Studio can leave the atom out of new generations. Defaults to false. Existing usages still render. See Validate and maintain an atoms catalog. |
If the atom accepts a class string, declare className inside its props schema. See Configure styling for atom-based components.
Use Sitecore field props
For props that authors edit as Sitecore fields, use the field-schema helpers. Each helper returns a Zod object with the matching field's { value: ... } shape and attaches an editor hint for Design Studio.
| Helper | Editor control | Field type | value shape |
|---|---|---|---|
textFieldSchema() | Single-Line Text | Text | Optional string or number |
numberFieldSchema() | Number | Number | Optional number |
richTextFieldSchema() | Rich Text | RichText | Optional string |
dateFieldSchema() | Date | Date | Optional string |
linkFieldSchema() | Link | Link | Object with Sitecore link attributes, including href, text, title, target, anchor, querystring, linktype, class, and className |
imageFieldSchema() | Image | Image | Optional object with src, alt, width, height, and class |
fileFieldSchema() | File | File | Object with src, title, and displayName |
Import the helpers from @sitecore-content-sdk/nextjs/atoms. For example, a component's props schema can include:
Each helper accepts an optional Zod shape and merges its keys into the field object. Link, image, and file values keep extra Sitecore attributes.
In the renderer, read the field value through the prop, for example props.heading?.value.
Use a numeric field prop
Use numberFieldSchema when a prop should use a Number field in Design Studio:
The field uses a { value: ... } shape. Read it in the renderer through props.quantity?.value.
Use textFieldSchema for text fields and numberFieldSchema for numeric fields. The numeric helper accepts decimal and negative numbers, and its value is optional. The SDK also exports the inferred NumberFieldSchema type. Configure minimum, maximum, and integer constraints on the field itself in Design Studio.
Add editor hints to other props
Use Zod directly for other props. Wrap a schema with withPropMeta when Design Studio should show a specific editor:
Use tone as a prop schema in the component's z.object. Both control and fieldType are optional. The SDK keeps the metadata when it converts the catalog's Zod schemas to JSON Schema for Design Studio.
Declare slots and placement
Use slots to declare where the atom accepts nested content. The renderer receives default-slot content as children and other slots through slots, keyed by name.
For example, a card renderer can use header and footer slots alongside default-slot content. Declare those names on its catalog entry:
When you omit slots, Design Studio receives ['default']. For a complete catalog and renderer example, see Implement atom renderers and slots.
Use allowedChildren to describe which atom names can appear in the atom's slots. Use allowedParents to describe which atoms can contain it. These placement fields describe the catalog sent to Design Studio.
Maintain the catalog
After an intentional change to a component definition, update the lock file. For lock-file commands, optional catalog and component versions, and legacy components, see Validate and maintain an atoms catalog.
If a component doesn't render or the catalog fails validation, see Troubleshoot atoms.