---
title: "Define an atoms catalog"
slug: "define-an-atoms-catalog"
abstract: "Define atom prop schemas, editor hints, slots, and placement constraints for Design Studio in a Content SDK Next.js app."
---
# 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](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 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:

```tsx
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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/implement-atom-renderers-and-slots.html) 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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/add-actions-and-state-bindings-to-atoms.html).

<!-- Reviewer: atoms.md lines 100-101 reference Icon, Card, and Stack without defining them in the sample catalog. This draft removes those placement entries rather than adding components absent from the sample. -->

## 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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/validate-and-maintain-an-atoms-catalog.html). |
| `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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/configure-styling-for-atom-based-components.html).

## 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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/validate-and-maintain-an-atoms-catalog.html). |
| `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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/validate-and-maintain-an-atoms-catalog.html). |

If the atom accepts a class string, declare `className` inside its `props` schema. See [Configure styling for atom-based components](https://doc.sitecore.com/sai/en/developers/content-sdk/20/configure-styling-for-atom-based-components.html).

<!-- Reviewer: atoms.md line 132 places className in the component-fields table, but its description says it is allowed on props. This draft treats className as a prop, not a top-level component field. The checked serializer has no top-level component className field. -->

## 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:

```tsx
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: 

```tsx
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:

```tsx
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:

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

When you omit `slots`, Design Studio receives `['default']`. For a complete catalog and renderer example, see [Implement atom renderers and slots](https://doc.sitecore.com/sai/en/developers/content-sdk/20/implement-atom-renderers-and-slots.html#render-default-and-named-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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/validate-and-maintain-an-atoms-catalog.html).

If a component doesn't render or the catalog fails validation, see [Troubleshoot atoms](https://doc.sitecore.com/sai/en/developers/content-sdk/20/troubleshoot-atoms.html).
