FREEFirst project with us? Your landing page design is on the house.See the offer

Chapter 3 of 6

Sanity schemas for sections

How to turn your plan into code: a page with a sections array, narrow fields, variants as fixed lists, rules on every field and an Astro component for each type.

6 min readUpdated 2026-11-07
All chaptersChapter 3 of 6
  1. 01Why sections, not pages
  2. 02Planning the library
  3. 03Sanity schemas for sections
  4. 04Studio for marketers
  5. 05AI page building with guardrails
  6. 06Testing and governance

The short answer

In Sanity, model each section as a named object type. Give the page document one array that accepts only those types. Use fixed lists for variants, length limits on text and required alt text on images. In Astro, map each section's _type to a component.

The samples here are examples we wrote for this guide, not code from a client project. We checked the syntax against Sanity's and Astro's docs. These tools change, so check the current docs before you copy anything. For a fuller list of modelling rules, read Structuring Sanity content for AI.

The page document

A page has a few page-level fields and one array. Listing the allowed members in of is what limits the page to your library. Anything not listed cannot be added in the Studio.

defineType({ name: 'page', type: 'document', fields: [ defineField({ name: 'title', type: 'string', validation: (rule) => rule.required() }), defineField({ name: 'slug', type: 'slug', options: { source: 'title' }, validation: (rule) => rule.required() }), defineField({ name: 'sections', type: 'array', of: [ defineArrayMember({ type: 'hero' }), defineArrayMember({ type: 'featureGrid' }), defineArrayMember({ type: 'faq' }) ], validation: (rule) => rule.required().min(1) }) ] })

Sanity gives each array item a unique _key, so you do not set it yourself. Add your SEO fields here too, in a field group so they sit in their own tab.

A section as a named object

Each section is its own object type, in its own file. One section, one file. Register it in your schema types with the others. Here is a sample hero, shortened:

defineType({ name: 'hero', title: 'Hero', type: 'object', fields: [ defineField({ name: 'heading', type: 'string', description: 'One line. Say what the page offers.', validation: (rule) => rule.required().max(60) }), defineField({ name: 'lead', type: 'text', rows: 3, validation: (rule) => rule.max(180) }) ] })

Set the limits from your design. Test the longest heading your layout can hold at phone width, and use that number. The 60 here is only a sample. Use description for short guidance on every field. Editors read it, and it is a good place to state the rule in plain words.

Variants as fixed lists

A variant is a string field with a fixed list of values. Radio buttons show every choice at once. Sanity's docs note that they also avoid the blank option a dropdown shows at the top.

defineField({ name: 'layout', type: 'string', options: { list: [ { title: 'Image right', value: 'imageRight' }, { title: 'Centred', value: 'centred' } ], layout: 'radio' }, initialValue: 'imageRight', validation: (rule) => rule.required() })

An initial value means a new section already looks right when added. If a field only applies to one variant, you can hide it with a callback:

hidden: ({ parent }) => parent?.layout === 'centred'

The docs we read do not say how a hidden required field behaves in validation, so test that combination in your Studio. And if you find yourself hiding half the fields, go back to the decision rule in chapter 2. It is probably two sections.

Images, rich text and references

Three field types need extra care, because this is where layouts and facts tend to break.

Images. Add alt text as a custom field on the image, and turn on the hotspot tool so crops keep the subject in view.

defineField({ name: 'image', type: 'image', options: { hotspot: true }, fields: [ defineField({ name: 'alt', type: 'string', validation: (rule) => rule.required() }) ] })

Rich text. Portable Text is powerful, so narrow it. Declaring styles, lists and marks replaces the default sets. A section body rarely needs its own headings, because the section already has one.

of: [{ type: 'block', styles: [{ title: 'Normal', value: 'normal' }], lists: [{ title: 'Bullet', value: 'bullet' }], marks: { decorators: [{ title: 'Strong', value: 'strong' }] } }]

Links stay available here, because the default link annotation remains unless you declare your own annotations.

References. Point to facts held elsewhere. A strong reference, the default, stops anyone deleting a testimonial that a live page still uses. That is usually what you want.

defineField({ name: 'quote', type: 'reference', to: [{ type: 'testimonial' }] })

Query the page with GROQ

Fetch the page and its sections with GROQ. The spread (...) returns every field of each section. A conditional adds what a particular type needs, such as following a reference with ->:

*[_type == 'page' && slug.current == $slug][0]{ title, sections[]{ ..., _type == 'quoteBlock' => { quote->{ text, name, role } } } }

For a static build, the official @sanity/astro integration gives you a client through import { sanityClient } from 'sanity:client', and its docs say to set useCdn: false. By default, recent API versions read published content only, which is what you want on the live site. Older API versions default to a different view, so set your API version on purpose.

Render sections in Astro

Astro supports dynamic tags, so one small loop can render any page. In the frontmatter, map each type name to its component:

const map = { hero: Hero, featureGrid: FeatureGrid, faq: Faq };

Then in the template:

{page.sections.map((s) => { const Section = map[s._type]; if (!Section) throw new Error('No component for ' + s._type); return <Section {...s} />; })}

  • Capitalise the variable. Astro treats a lower-case name as a literal HTML tag.
  • Fail the build on an unknown type. A schema with no component should stop the build, not leave a hole in a live page.
  • Keep client directives inside each component. Astro's docs say client:* does not work on a dynamic tag. Put the interactive island inside the section component instead.
  • Type your props. Add an interface Props to each section component.

Keep schema and code in step

Schema and components can drift apart, so make the machine check them.

  • Run sanity schemas validate to catch problems in your schema types.
  • Run Sanity TypeGen: npx sanity schema extract, then npx sanity typegen generate. It writes TypeScript types for your schema and your GROQ results, so a renamed field shows up as an error in your code.
  • Keep schemas in Git with the Astro code, and change them in the same pull request.

Done when A new page can be built in the Studio using only listed sections, every text field has a limit, every image needs alt text, and an unknown section type fails the build.

Takeaways

What to remember from chapter 3.

  • One sections array, with only your named types listed in of.
  • Variants are fixed lists. Limits come from testing your design at phone width.
  • Narrow rich text, require alt text, and point to facts with references.
  • Map _type to a component, and fail the build on an unknown type.
  • Check schemas and generate types, so code and content stay in step.

Your turn

Let's kook
what you krave.

Hi Kookies, I need a built on . I'd love to launch . Reach me at
or book a callSent. We reply within one working day.