Defining a section
A section is a full-width component editors place in a zone. You describe its fields once, in a schema file, and Smoodly derives the editor form, the Add section entry and the TypeScript props from that one definition. This page walks through the Lorem Co. starter's Hero.
The schema
A section is two files. Hero.schema.ts holds the schema: smoodly.schema.section() with a name, the title editors see, and a fields map built from the f helpers. The view, below, renders it. The schema is the same file in every framework; in an Astro project it lives under src/components/sections/.
import { f, smoodly } from "smoodly";
export const heroSchema = smoodly.schema.section({
name: "hero",
title: "Hero",
description: "The home page opener: heading, text, buttons and a photo.",
fields: {
kicker: f.text().optional(),
heading: f.text(),
text: f.text(),
buttons: f.list(f.object({ label: f.text(), href: f.link() })).max(2),
image: f.image({ aspect: "4:5" }),
},
sample: {
// …
},
});nameWhat the content stores for every placed Hero, so keep it stable once pages exist.titleThe label in Add section and in the inspector.descriptionA line about the section, kept for later use: the admin does not show it today. Optional, like icon.fieldsWhat editors fill. Field order is form order: editors see Kicker, Heading, Text, Buttons, Image, top to bottom.sampleWhat a new Hero starts with. See Sample content below.Every field is required unless it chains .optional(). .max() and .min() limit a length or a count, .default() sets a starting value, and .localized() gives a field its own value per language. The full list is on All fields.
The view
The view is an .astro file named after the schema: src/sections/hero.astro renders the section named hero. It imports the schema, and Props<typeof heroSchema> types Astro.props: the fields flat, plus settings and styles.
---
import { safeHref, smoodly, type Props as SmoodlyProps } from "smoodly";
import { Image, Section } from "smoodly/astro/components";
import { heroSchema } from "@/components/sections/Hero.schema";
type Props = SmoodlyProps<typeof heroSchema>;
const { kicker, heading, text, buttons, image, styles } = Astro.props;
const m = smoodly.marks(heroSchema);
---
<Section styles={styles} class="hero">
// …
<h1 class="hero__heading" {...m.field("heading")}>{heading}</h1>
// …
{buttons.map((b, i) => {
const button = m.item("buttons", i);
return <a class={i === 0 ? "button" : "button button--outline"} href={safeHref(b.href)} {...button.attrs} {...button.field("label")}>{b.label}</a>;
})}
// …
{image && <Image image={image} class="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
// …
</Section>Three things make this a section rather than a plain component:
Sectionis the root element. It comes fromsmoodly/astro/components. Pass itstyles, and it renders the spacing and width steps an editor picks, plus the attribute the canvas uses to select the section.as="header"changes the tag;class,idanddata-attributes pass through. The section's own CSS is yours, insrc/styles/global.csslike the starter's.- Marks make fields click-to-edit.
smoodly.marks(heroSchema)returns typed helpers. Spreadm.field("heading")on the element that renders the heading, and clicking it in the canvas opens that field. For a list,m.item("buttons", i)gives a scope: spread itsattrson the item's root and mark the fields inside withfield().m.object()does the same for an object field. Outside the admin the marks are plaindata-attributes. Marks and inline editing has the details. - The file name pairs the two. There is no pairing line and no list of views. The server names a schema with no file, and a file with no schema, at the first request.
A link an editor typed goes through safeHref from smoodly: Astro writes an attribute as given, so a javascript: URL would reach the page. safeHref passes http(s), mailto, tel and site paths, and gives null for anything else, so the link renders with no href.
The view is an ordinary React component in Hero.tsx, beside the schema. It imports the schema, and Props<typeof heroSchema> types it: the fields flat, plus settings and styles.
const m = smoodly.marks(heroSchema);
function HeroView({ kicker, heading, text, buttons, image, styles }: Props<typeof heroSchema>) {
return (
<smoodly.Section styles={styles} className="hero">
<div className="container hero__grid">
<div className="hero__copy">
{kicker && <p className="kicker" {...m.field("kicker")}>{kicker}</p>}
<h1 className="hero__heading" {...m.field("heading")}>{heading}</h1>
<p className="hero__text" {...m.field("text")}>{text}</p>
{buttons?.length > 0 && (
<div className="hero__buttons">
{buttons.map((b, i) => {
const button = m.item("buttons", i);
return (
<a key={i} className={i === 0 ? "button" : "button button--outline"} href={b.href}
{...button.attrs} {...button.field("label")}>{b.label}</a>
);
})}
</div>
)}
</div>
{image && <SmoodlyImage image={image} className="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
</div>
</smoodly.Section>
);
}
export const Hero = smoodly.section(heroSchema, HeroView);Three things make this a section rather than a plain component:
smoodly.Sectionis the root element. Pass itstyles, and it renders the spacing and width steps an editor picks, plus the attribute the canvas uses to select the section.as="header"changes the tag;className,idanddata-attributes pass through. The section's own CSS is yours, inapp/globals.csslike the starter's.- Marks make fields click-to-edit.
smoodly.marks(heroSchema)returns typed helpers. Spreadm.field("heading")on the element that renders the heading, and clicking it in the canvas opens that field. For a list,m.item("buttons", i)gives a scope: spread itsattrson the item's root and mark the fields inside withfield().m.object()does the same for an object field. Outside the admin the marks are plaindata-attributes. Marks and inline editing has the details. smoodly.section()pairs the two. Rename a field in the schema and this line fails to compile until the view follows. The export is the component you list insmoodly/views.ts. It renders as a normal component too, so you can place a section in your own JSX with its fields as props.
When a section throws
If a section's own code throws, for example on data it didn't expect, the page still renders and that section is left out. The error goes to the server log, and the editor's canvas shows a placeholder in its place. The editor names it too, and Publish asks before a page with a broken section goes live.
The zone renders each section through Astro.slots.render inside a try/catch, so a throw anywhere inside the section, a component it renders included, leaves the section out and the page renders.
next dev shows the placeholder too. A throw inside a component the section renders, or in a 'use client' section, still fails the live page, but in the canvas it is caught and named the same way, so it shows up before anyone publishes.
Registering it
Add the schema to src/smoodly/sections.ts, which the config registers. The view is the file; there is nothing else to list. Editors can place the section only once a zone lists it, which is the next step:
import { heroSchema } from "@/components/sections/Hero.schema";
// …
export const sections = [heroSchema, pageHeroSchema, imageTextSchema, pointsSchema, favouriteArticlesSchema, peopleSchema, quoteSchema, headerSchema, footerSchema];A section is registered in two lists. Add its schema to smoodly/sections.ts, which the config registers, and its component to sections in smoodly/views.ts. The config imports no component, so the CLI, a seed script and an agent can read your content model without loading React. Editors can place the section only once a zone lists it, which is the next step:
import { heroSchema } from "@/components/sections/Hero.schema";
// …
export const sections = [heroSchema, pageHeroSchema, imageTextSchema, pointsSchema, favouriteArticlesSchema, peopleSchema, quoteSchema, headerSchema, footerSchema];import { Hero } from "@/components/sections/Hero";
// …
export const views = () =>
defineViews(config, {
sections: [Hero, PageHero, ImageText, Points, FavouriteArticles, People, Quote, Header, Footer],
// …
});A schema with no component in smoodly/views.ts stops the first render with a named error: smoodly: section "hero" is registered in the config but has no view — add its component to defineViews({ sections }).
Registering makes the section known; a page type's zones decide where editors may use it. Lorem Co.'s home page locks its hero and lets the body take five sections:
export const homeSchema = smoodly.schema.page({
name: "home",
title: "Home",
slug: "home",
zones: {
hero: z.locked(heroSchema),
body: z.freeform({ sections: [imageTextSchema, pointsSchema, favouriteArticlesSchema, peopleSchema, quoteSchema], custom: true }),
},
// …
});A registered section that no zone lists never appears in Add section. Lorem Co.'s Header and Footer are registered that way, because the layout renders them as globals. The three policies are on Zones and freedom.
Sample content
sample is what a section starts with, so a page never shows an empty one. Smoodly uses it three times:
- Add section shows each section as your site draws it with its sample, so an editor sees what they are about to add.
- When an editor picks the section in Add section, the new section carries the sample.
- When a page opens with an empty locked zone, Smoodly fills the zone from the locked section's sample.
What Smoodly shows is what it inserts: the picture and the new section are built by the same rules.
The sample always comes first. A field it sets is taken as it is, and nothing is added to it or inside it. A field it leaves out starts from its .default(). A field with neither is filled by Smoodly, so a section with a thin sample still looks like itself:
f.text()Required: a short Latin phrase where the key reads as a title (title, heading, label, name, button and the like), else one sentence, cut to .max(n). Optional: empty.f.richtext()Required: a heading, two paragraphs and a list where the toolset has them, else one paragraph. Optional: empty.f.image()A placeholder picture, required or optional. It shows in the editor and in previews only, never on the live page; publishing treats it as no image, so a required image still asks for a photo.f.ref(), f.refList()The collection's first published entries: one for a required f.ref, up to three for an f.refList, fewer if .max(n) is lower.f.list(item)Required: .min(n) items, or three, never more than .max(n). Each item is filled the same way.f.object({ … })Required: its fields, filled the same way.Numbers, dates, links, videos and files are not filled (a number, a video and a file stay unset; a date and a link start empty), a list nothing fills starts as an empty list, and settings are never filled: they keep their defaults. An empty list in a sample (people: []) counts as left out. To choose the content yourself, put it in the sample.
Add section has an Insert filled switch under its list. Turned off, a section arrives empty: without the sample and without anything generated. The picture still shows the filled section.
The sample may set settings too, under their own keys.
Settings
Fields are content. Settings are your own options for how the section looks, which the view alone interprets. Lorem Co.'s Image and text lets editors put the photo on either side:
export const imageTextSchema = smoodly.schema.section({
name: "imageText",
title: "Image and text",
// …
settings: {
imageSide: f.radio([{ value: "left", label: "Image left" }, { value: "right", label: "Image right" }]).default("left"),
},
// …
});---
// …
const { image, heading, text, link, settings, styles } = Astro.props;
// …
---
<Section styles={styles} class="image-text" data-image-side={settings.imageSide}>function ImageTextView({ image, heading, text, link, settings, styles }: Props<typeof imageTextSchema>) {
// …
<smoodly.Section styles={styles} className="image-text" data-image-side={settings.imageSide}>The view receives settings with defaults filled, so settings.imageSide is always a value. Settings use the same f builders as fields, with one rule: they are never localized, because a layout choice is the same in every language.
In the inspector, fields are on the Content tab and settings on the Settings tab, above Smoodly's own Spacing & layout group. Settings, styles and CSS covers that group, styles: false for a section that should not offer it, and the custom CSS box.
The fields used here
f.text()Single line.max(n) limits the length in characters.f.link()Text boxA full URL or a site path such as /company/about-us.f.image({ aspect })Media pickerUpload or pick from the library, then crop to the aspect for this use.f.list(item)RepeaterEditors add, reorder and remove items. .min(n) and .max(n) count items; lists cannot nest.f.object({ … })A group of fieldsOne value with named parts, such as a button's label and href.f.richtext({ toolset })Text editorFormatted text; the toolset decides which formatting and elements it offers.f.radio([…])PillsOne value from a closed set. f.select([…]) shows the same set as a dropdown.Next, Page types shows where zones come from, and Zones and freedom how to set each zone's policy.