2.x
  1. Atoms in Content SDK apps (Early Access)

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.

Important

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:

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

export const catalog = defineAtomsCatalog({
  components: {
    Button: {
      props: z.object({
        label: textFieldSchema(),
        variant: z.enum(['primary', 'secondary']),
      }),
      description: 'A button that emits a press event',
      slots: ['default'],
      example: { label: { value: 'Continue' }, variant: 'primary' },
    },
  },
  actions: {},
});

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

FieldRequiredPurpose
componentsYesComponent definitions, keyed by atom name.
actionsYesAction definitions, keyed by action name. Use an empty object when there are none.
versionNoVersion of the whole catalog. Stored in the lock file and sent to Design Studio. See Validate and maintain an atoms catalog.
stylingSolutionNotailwind 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

FieldRequiredPurpose
propsYesZod object schema for the atom's props.
descriptionNoDescribes the atom for Design Studio generation.
slotsNoSlot names the atom accepts. When omitted, Design Studio receives ['default'].
allowedChildrenNoAtom names that can be placed in this atom's slots. Sent to Design Studio with the catalog.
allowedParentsNoAtom names this atom can be placed inside.
exampleNoSample prop values sent to Design Studio.
versionNoComponent version, checked separately from the definition hash. See Validate and maintain an atoms catalog.
legacyNoWhen 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.

HelperEditor controlField typevalue shape
textFieldSchema()Single-Line TextTextOptional string or number
numberFieldSchema()NumberNumberOptional number
richTextFieldSchema()Rich TextRichTextOptional string
dateFieldSchema()DateDateOptional string
linkFieldSchema()LinkLinkObject with Sitecore link attributes, including href, text, title, target, anchor, querystring, linktype, class, and className
imageFieldSchema()ImageImageOptional object with src, alt, width, height, and class
fileFieldSchema()FileFileObject with src, title, and displayName

Import the helpers from @sitecore-content-sdk/nextjs/atoms. For example, a component's props schema can include:

import { z } from 'zod';
import {
  textFieldSchema,
  richTextFieldSchema,
  dateFieldSchema,
  linkFieldSchema,
  imageFieldSchema,
  fileFieldSchema,
  numberFieldSchema,
} from '@sitecore-content-sdk/nextjs/atoms';

const props = z.object({
  heading: textFieldSchema(),
  body: richTextFieldSchema(),
  publishedOn: dateFieldSchema(),
  cta: linkFieldSchema(),
  media: imageFieldSchema(),
  download: fileFieldSchema(),
  quantity: numberFieldSchema(), 
});

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:

import { z } from 'zod'; 
import { numberFieldSchema } from '@sitecore-content-sdk/nextjs/atoms'; 
 
const props = z.object({ 
  quantity: numberFieldSchema(), 
});

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:

import { z } from 'zod';
import { withPropMeta } from '@sitecore-content-sdk/nextjs/atoms';

const tone = withPropMeta(z.enum(['neutral', 'accent']), {
  control: 'Select',
  fieldType: 'Select',
});

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:

slots: ['header', 'footer'],

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.

If you have suggestions for improving this article, let us know!