# Settings, styles and CSS

Beyond its fields, a placed section carries three more things editors can change: the settings you declare, Smoodly's own spacing and width steps, and a custom CSS box you can turn on. All three sit on the Settings tab.

## What a section carries

Every section on a page stores four groups of values:

| Group | Who defines it | Where editors find it |
| --- | --- | --- |
| `fields` | You, in the schema. The content. | The Content tab. |
| `settings` | You, in the schema. Options for how the section looks. | The Settings tab, at the top. |
| `styles` | Smoodly. Spacing, width and alignment steps. | The Settings tab, under Spacing & layout. |
| `css` | Smoodly, when the config turns it on. A CSS snippet for this one section. | The Settings tab, under Advanced. |

The view receives the first three as props: the fields flat, then `settings` and `styles`. The CSS never reaches the view; the section wrapper renders it.

## Settings

Settings use the same `f` builders as fields. The starter's Quote offers two backgrounds:

File: `components/sections/Quote.schema.ts`

```ts
export const quoteSchema = smoodly.schema.section({
  name: "quote",
  title: "Quote",
  // …
  settings: {
    background: f.radio([{ value: "paper", label: "Paper" }, { value: "ink", label: "Ink" }]).default("paper"),
  },
  // …
});
```

**Astro**

File: `src/sections/quote.astro`

```astro
---
// …
const { text, attribution, settings, styles } = Astro.props;
// …
---
<Section styles={styles} class="quote" data-background={settings.background}>
```

**Next.js**

File: `components/sections/Quote.tsx`

```tsx
function QuoteView({ text, attribution, settings, styles }: Props<typeof quoteSchema>) {
  return (
    <smoodly.Section styles={styles} className="quote" data-background={settings.background}>
```

The view alone interprets a setting. Here it becomes a data attribute that the stylesheet reads; it could as well pick a class or a layout branch. `settings` arrives with defaults filled, so `settings.background` is always one of the two values.

Two rules set settings apart from fields. They are never localized, because a layout choice is the same in every language, and `.localized()` on a setting throws at startup. And a sample may set them under their own keys, next to the fields.

## Hiding a field on a condition

A field or setting can leave the form while a condition holds. A media section that shows either a photo or a video needs only one of its two fields at a time:

**Astro**

The schema goes in `src/components/sections/Media.schema.ts`, written as in the Next.js tab: a schema is the same in every framework. Its view, `src/sections/media.astro`, renders `<Section styles={styles} class="media" data-kind={settings.kind}>` and shows the video or the image by `settings.kind`.

**Next.js**

File: `components/sections/Media.tsx`

```tsx
import { f, smoodly, type Props } from "smoodly/react";

export const mediaSchema = smoodly.schema.section({
  name: "media",
  title: "Media",
  fields: {
    image: f.image({ aspect: "16:9" }).hidden(f.when("settings.kind").is("video")),
    video: f.video().hidden(f.when("settings.kind").is("image")),
    caption: f.text().optional(),
  },
  settings: {
    kind: f.radio([{ value: "image", label: "Photo" }, { value: "video", label: "Video" }]).default("image"),
  },
});

function MediaView({ image, video, caption, settings, styles }: Props<typeof mediaSchema>) {
  return (
    <smoodly.Section styles={styles} className="media" data-kind={settings.kind}>
      {settings.kind === "video" ? <video src={video?.url} controls /> : <img src={image?.url} alt={image?.alt ?? ""} />}
      {caption && <p className="media__caption">{caption}</p>}
    </smoodly.Section>
  );
}

export const Media = smoodly.section(mediaSchema, MediaView);
```

`f.when(path)` reads a value and offers `.is()`, `.isNot()`, `.in([…])`, `.isEmpty()` and `.isNotEmpty()`. A bare path names a sibling at the same level, so inside an object or a list item it reads that item. A path prefixed `fields.` or `settings.` reads a top-level key of that group. A hidden field is skipped at publish, and its stored value stays, so switching back restores it. A condition that names a field that does not exist fails at startup, not in the form.

## Smoodly's styles

Every section gets four steps under *Spacing & layout*, whatever its schema says:

| Step | Options | Renders as |
| --- | --- | --- |
| `Spacing top, Spacing bottom` | Default · 0 · S · M · L | padding-top and padding-bottom, inline on the section root. |
| `Width` | Default · Narrow · Wide · Full | The --smd-width variable on the section root; your container reads it. |
| `Align` | Default · Left · Center · Right | text-align on the section root. |

*Default* stores and renders nothing, so a section looks exactly as you wrote it until an editor reaches for a step. *0* is a real step, because two dark sections meeting need your padding removed, not added. Editors never see pixels or breakpoints.

The config supplies the CSS behind each step. The starter points them at variables its stylesheet defines per breakpoint:

File: `smoodly/config.ts`

```ts
export const config = defineConfig({
  // …
  styles: {
    spacing: { sm: "var(--space-sm)", md: "var(--space-md)", lg: "var(--space-lg)" },
    width: { narrow: "var(--width-narrow)", wide: "var(--width-wide)", full: "none" },
  },
  // …
});
```

File: `app/globals.css`

```css
:root {
  --space-sm: 24px; --space-md: 48px; --space-lg: 72px;
  --width-narrow: 640px; --width-wide: 1440px;
  --container: 1200px;
}
@media (min-width: 768px) { :root { --space-sm: 32px; --space-md: 64px; --space-lg: 96px; } }

/* The container reads the editor's width step; without one, the design's width. */
.container { max-width: var(--smd-width, var(--container)); width: 100%; margin: 0 auto; padding-inline: 32px; }
```

Width is a variable rather than a `max-width` on the section, so a section with a background stays full-bleed while its content narrows. Only your container knows it is the container, so give it the rule above. Without a `styles` entry in the config the package's own fallbacks apply.

Two things make the steps work in a view: the root element is Smoodly's section wrapper, and it receives the `styles` prop. A section that renders its own root gets no steps.

**Astro**

The wrapper is `<Section styles={styles}>` from `smoodly/astro/components`.

**Next.js**

The wrapper is `<smoodly.Section styles={styles}>` from `smoodly/react`.

To take the group away from a section, set `styles: false` in its schema, as the starter's header and footer do, or `styles: { omit: ["align"] }` to drop some steps. Elements never have styles: spacing is their container's job.

## Custom CSS

Turn the box on for the whole site in the config:

File: `smoodly/config.ts`

```ts
export const config = defineConfig({
  // …
  css: true,
  // …
});
```

Every section then has a *Custom CSS* box under *Advanced* on its Settings tab, and `css: false` in a schema opts one section out. What an editor types is nested inside the section's own selector, so declarations apply to the section root and nested selectors reach inside it:

```css
background: var(--ink);
color: var(--paper);
h2 { font-size: 40px; }
```

The snippet is scoped, so it cannot restyle another section or the page. It is also checked as it is typed and again at publish, and refused when it uses `@import`, `url()`, `expression()` or `behavior:`, contains `</`, leaves a brace unclosed, or runs past 4000 characters. The layout of the [custom section](https://smoodly.io/docs/content-modeling/custom-section.md) is emitted the same way, before the editor's own snippet, so the box still wins.

Next, [The custom section](https://smoodly.io/docs/content-modeling/custom-section.md) covers the one layout editors build themselves.
