---
title: "Configure styling for atom-based components"
slug: "configure-styling-for-atom-based-components"
abstract: "Configure the catalog styling solution and runtime CSS compilation for atom-based component layouts."
---
# Configure styling for atom-based components

Class names in component layouts can be absent from your app's source files, so the production CSS build doesn't include them. Runtime CSS compilation lets the SDK style these class names when it renders a layout and during Design Studio editing.

This topic assumes you have connected a catalog and registry to `SitecoreProvider`. 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.

## Set the catalog styling solution

In `src/atoms/index.tsx`, set `stylingSolution: 'tailwind'` on the existing catalog when your app styles atoms with Tailwind. For example, an empty catalog with this setting is:

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

export const catalog = defineAtomsCatalog({
  stylingSolution: 'tailwind',
  components: {},
  actions: {},
});
```

`stylingSolution` tells Design Studio whether to generate Tailwind classes or inline CSS. Its values are `tailwind` and `inline-css`; the default is `inline-css`. The SDK sends this setting with the catalog. It doesn't register a runtime CSS compiler.

For other catalog settings, see [Define an atoms catalog](https://doc.sitecore.com/sai/en/developers/content-sdk/20/define-an-atoms-catalog.html).

## Enable site-level theming

Site-level theming loads a design-token stylesheet for the current SitecoreAI site. Enable it through `theming.mode` in `sitecore.config.ts`. This configuration is separate from the catalog's `stylingSolution` and runtime atom CSS compilation:

| Setting                                          | Purpose                                                                   |
| :----------------------------------------------- | :------------------------------------------------------------------------ |
| Catalog `stylingSolution`                        | Tells Design Studio whether the app uses Tailwind classes or inline CSS.  |
| registerTailwindCssCompiler and compileCssAction | Compile class names used in atom-based component layouts.                 |
| Site configuration theming.mode                  | Controls whether the SDK includes the site-level design-token stylesheet. |

### Configure theming mode

In the existing sitecore.config.ts, add theming to the defineConfig configuration: 

```ts
import { defineConfig } from '@sitecore-content-sdk/nextjs/config'; 
 
export default defineConfig({ 
  theming: { 
    mode: 'site', 
  }, 
});
```

Keep the other settings already configured in your app. 


The Next.js configuration reads the client context ID from `NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID`, unless you explicitly configure `api.edge.clientContextId`.

### Include the theme stylesheet

The SDK's SitecoreClient.getHeadLinks method includes the site-level theme stylesheet when: 

* `theming.mode` is `site`.
* The layout response contains `sitecore.context.site.name`. 
* A client Edge context ID is configured.

The starters created using the CLI render these links through their `SitecoreStyles` component and construct the SDK client with the application configuration. In an existing app, ensure your SDK client receives the theming configuration and your page renders the links returned by `getHeadLinks`.

The site-level theme stylesheet uses this URL structure: 

```bash
{edge}/authoring/api/v1/themes/delivery/{siteName}/web-css?contextID={clientContextId} 
```

Site-level theming is independent of the `enableThemes` option used for Design Studio stylesheets. Setting `enableThemes` to `false` doesn't disable site-level theming. Use `theming.mode: 'none'` to disable it.

### Apply the theme class to the page 

The starters conditionally add `sc-ds-theme` to `<body>` when site-level theming is enabled. 

For an existing app, import the configuration and helpers in the file that renders `<body>`:

```ts
import scConfig from 'sitecore.config'; 
import { 
  isSiteThemingEnabled, 
  THEMING_BODY_CLASS_NAME, 
} from '@sitecore-content-sdk/nextjs';
```

Use this expression for the theme class: 

```jsx
<body 
  className={ 
    isSiteThemingEnabled(scConfig.theming.mode) 
      ? THEMING_BODY_CLASS_NAME 
      : undefined 
  } 
> 
  {/* Existing body content */} 
</body>
```

Apply the change in:

* `src/app/layout.tsx` for App Router and App Router with Cache Components. 
* `src/pages/_document.tsx` for Pages Router. 
* If `<body>` already has classes, combine the theme class with those classes.

### Expose the theming configuration to the editor

Pass the same theming configuration to the editing configuration endpoint so SitecoreAI can determine the application's theming configuration.

For App Router and Cache Components, add theming to the existing options in `src/app/api/editing/config/route.ts`:

```ts
export const { GET, OPTIONS } = createEditingConfigRouteHandler({ 
  components, 
  clientComponents, 
  metadata, 
  theming: scConfig.theming, 
});
```

For Pages Router, add it to the existing middleware options in src/pages/api/editing/config.ts: 

```ts
const handler = new EditingConfigMiddleware({ 
  components, 
  metadata, 
  theming: scConfig.theming, 
}).getHandler(); 
 
export default handler;
```

Import `scConfig` from `sitecore.config` if the file doesn't already import it. Keep the endpoint's existing imports, options, and exports.

### Verify the integration

After restarting the app:

1. Open a page for the configured SitecoreAI site. 
2. Inspect `<body>` and confirm that its classes include `sc-ds-theme`. 
3. Inspect the rendered stylesheet links and confirm that one uses the site-theme delivery URL. 
4. In the browser's network tools, check that the theme stylesheet request succeeds. 
5. Check the editing configuration response and confirm that its theming object has `mode: 'site'`. 

If the stylesheet link is missing, check the theming mode, site name in the layout response, and client Edge context ID. 

This procedure configures the SDK to load a site theme. It doesn't create or assign tokens or Token Sets in SitecoreAI.

## Preview theme changes

The SDK can apply theme CSS updates while a page is in editing or preview mode. This lets the preview reflect theme changes without replacing the site's delivered stylesheet link. The starters pass the theming configuration to `SitecoreProvider`. For an existing app, import `scConfig` from `sitecore.config` if necessary and add this prop to the existing provider: 

```ts
theming={scConfig.theming}
```

Keep the provider's other props, including `atomsConfig`. Retain the app's `EditingScripts` integration. The SDK's `EditingScripts` component includes `ThemePreviewEvents`, which listens for theme-update messages in editing and preview modes. Apps using this integration don't need a second theme-update listener. 

When a valid update arrives, the SDK applies the CSS in a preview `<style>` element. A later update replaces that element; an empty CSS update removes it. These updates change the preview and don't save or publish the theme. 

Set `theming.mode` to site to use the configured site theme and its preview integration. The listener is inactive when the configured mode is none, and the SDK doesn't include it on normal pages through `EditingScripts`. 

This behavior is separate from `compileCssAction`, which compiles classes in atom-based layouts. For preview issues, see [Troubleshoot atoms](https://doc.sitecore.com/sai/en/developers/content-sdk/20/troubleshoot-atoms.html). 

## Check the starter configuration

The starters include different CSS compilation configuration:

| Starter | Configuration |
| --- | --- |
| App Router | Registers the Tailwind compiler at startup and passes `compileCssForDocumentAction` to the provider. |
| App Router with Cache Components | Registers the Tailwind compiler at startup and passes `compileCssForDocumentAction` to the provider. |
| Pages Router | Includes the catalog, registry, provider, and CLI commands, but doesn't register a CSS compiler. Atoms still render without one. |

The following Tailwind setup describes the App Router and Cache Components integration.

<!-- Note for later: atoms.md line 352 instructs Pages Router apps to pass compileCssForDocumentAction using the same calls as App Router. At origin/release/betas/atoms, packages/create-content-sdk-app/src/templates/nextjs/src/Providers.tsx repeats this only in a comment; its provider doesn't pass compileCssAction. packages/nextjs/src/server-actions/compile-document-css-action.ts uses 'use server', and packages/react/src/atoms/types.ts documents this action for App Router starters. These files don't verify a working Pages Router Server Action integration. The Pages Router runnable instructions are omitted pending confirmation; no replacement integration is inferred. -->

## Register the Tailwind compiler at startup

Published pages use the compiler registered when the server starts. The SDK collects class tokens from each layout element's `className` prop and passes them to that compiler.

The App Router and Cache Components starters use these startup files:

```ts
// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node');
  }
}
```

```ts
// instrumentation-node.ts
import { registerTailwindCssCompiler } from '@sitecore-content-sdk/nextjs/instrumentation';

await registerTailwindCssCompiler('src/app/globals.css');
```

Pass the path to your app's Tailwind stylesheet. A relative path resolves from the app root. With no argument, `registerTailwindCssCompiler` uses `src/app/globals.css`.

Keep `@tailwindcss/node` in `serverExternalPackages` in the Next.js configuration because it ships native binaries:

```ts
serverExternalPackages: ['@tailwindcss/node'],
```

## Compile CSS during Design Studio editing

Design Studio editing uses `compileCssAction` to call the same registered compiler. In the App Router and Cache Components starters, `src/Providers.tsx` imports the Server Action:

```tsx
import { compileCssForDocumentAction } from '@sitecore-content-sdk/nextjs/server-actions';
```

Pass it as `compileCssAction` on the existing provider's `atomsConfig`:

```tsx
atomsConfig={{
  catalog,
  registry,
  navigate: router.push,
  compileCssAction: compileCssForDocumentAction,
}}
```

`compileCssForDocumentAction` returns an empty string when no compiler is registered or the document has no class names. Setting `stylingSolution: 'tailwind'` alone doesn't enable this compilation.

If a document contains class names but no compiler is registered, the component still renders without compiled CSS for those classes. For related issues, see [Troubleshoot atoms](https://doc.sitecore.com/sai/en/developers/content-sdk/20/troubleshoot-atoms.html).

## Use a custom CSS compiler

To use a compiler other than Tailwind, register it once from Node.js startup code with `setAtomsCssCompiler`:

```ts
import { setAtomsCssCompiler } from '@sitecore-content-sdk/core';

setAtomsCssCompiler(async (classes) => {
  return compileClasses(classes);
});
```

This snippet is illustrative: `compileClasses` is a placeholder for your own compiler implementation, not a Content SDK API. The registered function must accept `string[]` class tokens and return `Promise<string>` containing the compiled CSS.

The registration is shared by instrumentation, React Server Components, and Server Actions. Published rendering and the editing action use the same registered compiler.
