---
title: "Implement atom renderers and slots"
slug: "implement-atom-renderers-and-slots"
abstract: "Register React renderers for atoms, render default and named slots, and pass the registry to SitecoreProvider in a Content SDK Next.js app."
---
# Implement atom renderers and slots

The atoms registry maps catalog names to React renderers and action handlers. Each renderer displays an element's props and places its nested content in default or named slots.

For app setup, see [Get started with atoms](https://doc.sitecore.com/sai/en/developers/content-sdk/20/get-started-with-atoms.html). For prop schemas and catalog metadata, see [Define an atoms catalog](https://doc.sitecore.com/sai/en/developers/content-sdk/20/define-an-atoms-catalog.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.

## Render default and named slots

Call `defineAtomsRegistry` with the catalog and a matching `components` map. Use the same keys in both maps.

The following example defines a card with a title prop, declares named slots, and renders both named-slot and default-slot content:

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

export const catalog = defineAtomsCatalog({
  components: {
    Card: {
      props: z.object({ title: z.string() }),
      description: 'A content card',
      slots: ['header', 'footer'],
    },
  },
  actions: {},
});

export const registry = defineAtomsRegistry(catalog, {
  components: {
    Card: ({ props, children, slots }) => (
      <section>
        <header>{slots?.header}</header>
        <h2>{props.title}</h2>
        {children}
        <footer>{slots?.footer}</footer>
      </section>
    ),
  },
});
```

In a component layout, `children` lists element keys for the default slot. The element's `slots` map lists element keys for each named slot. The renderer receives the rendered content:

- `children` contains the default slot.
- `slots?.header` contains the `header` slot.
- `slots?.footer` contains the `footer` slot.

Declare named slots on the catalog entry so Design Studio knows which slots the atom accepts. When the catalog entry omits `slots`, Design Studio receives `['default']`.

## Renderer arguments

Each renderer receives an object with the following properties:

| Property   | Purpose                                                                                                                        |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `props`    | Props for the element. For a Sitecore field prop, read its value through the field object, for example `props.heading?.value`. |
| `children` | Content of the default slot.                                                                                                   |
| `slots`    | Content of every other slot, keyed by slot name.                                                                               |
| `emit`     | Fires a named event, for example `emit('press')`. The runtime resolves the event from the element's `on` binding.              |
| `on`       | Returns an event handle. For example, `on('press')` returns `{ emit, shouldPreventDefault, bound }`.                           |
| `bindings` | Maps a prop bound with `$bindState` or `$bindItem` to its state path. Present when at least one prop is bound.                 |

The element's `on` field is layout data. The renderer's `on` property is a function for inspecting and firing an event binding.

For event handlers, action registration, and two-way props with `useBoundProp`, 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).

## Connect the registry to the provider

`defineAtomsRegistry` returns `{ registry, handlers, executeAction }`. Keep this whole result in the exported `registry` variable and pass it to `atomsConfig.registry`.

1. In the existing `src/Providers.tsx`, import the catalog and registry:

  ```tsx
  import { catalog, registry } from 'src/atoms';
  ```

2. Add the following prop to the existing `SitecoreProvider`:

  ```tsx
  atomsConfig={{ catalog, registry }}
  ```

3. Pass the whole result, rather than only its nested `registry` property. A component without a matching renderer doesn't render. A catalog action without a handler doesn't run.

`defineAtomsRegistry` is a Client Component module. The starters import it through `src/Providers.tsx`. Keep the registry integration in that client provider in App Router apps.

If the provider already passes `navigate` or `compileCssAction` on `atomsConfig`, keep those properties. For route changes, 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). For 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).

## Validate catalog changes

If you change a component definition while adding its renderer or slots, update the lock file. 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 an atom or component layout doesn't render, see [Troubleshoot atoms](https://doc.sitecore.com/sai/en/developers/content-sdk/20/troubleshoot-atoms.html).
