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

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. For prop schemas and catalog metadata, see Define an atoms catalog.

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.

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:

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:

PropertyPurpose
propsProps for the element. For a Sitecore field prop, read its value through the field object, for example props.heading?.value.
childrenContent of the default slot.
slotsContent of every other slot, keyed by slot name.
emitFires a named event, for example emit('press'). The runtime resolves the event from the element's on binding.
onReturns an event handle. For example, on('press') returns { emit, shouldPreventDefault, bound }.
bindingsMaps 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.

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:
import { catalog, registry } from 'src/atoms';
  1. Add the following prop to the existing SitecoreProvider:
atomsConfig={{ catalog, registry }}
  1. 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. For CSS compilation, see Configure styling for atom-based components.

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.

If an atom or component layout doesn't render, see Troubleshoot atoms.

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