Blocks
Build page sections from block types with block() and the blocks field.
On this page
This page shows how to define block types and use them in a blocks field, so editors can compose pages from sections you control.
A block is a named set of fields, such as a hero or a call to action. A blocks field holds an ordered list of them. Editors can only add the block types you list, so the layout stays inside your design.
Define blocks
import { block, collection, fields as f } from '@kitcms/core';
const Hero = block({
slug: 'hero',
fields: {
heading: f.text({ required: true }),
subheading: f.textarea(),
image: f.upload({ relationTo: 'media' }),
},
});
const Cta = block({
slug: 'cta',
labels: { singular: 'Call to action', plural: 'Calls to action' },
fields: {
heading: f.text({ required: true }),
buttonLabel: f.text({ required: true }),
buttonHref: f.text({ required: true }),
},
});
const pageBlocks = [Hero, Cta] as const;
export const pages = collection({
slug: 'pages',
versions: { drafts: { autosave: true } },
access: { read: () => true },
fields: {
title: f.text({ required: true }),
sections: f.blocks({ blocks: pageBlocks }),
},
});Declare the list as const. That keeps each block's slug as a literal type, which the document type needs.
Block options
| Option | What it does |
|---|---|
slug |
Stored as blockType on each block. Unique within one blocks field. Required. |
fields |
The block's fields. Required. |
labels |
{ singular, plural } for the admin. |
What a stored block looks like
Each block in the list is an object with its own id, its blockType and its fields:
{ "id": "01J...", "blockType": "hero", "heading": "Welcome" }The type of sections is a union of the block shapes, so checking blockType narrows it:
for (const block of page.sections) {
if (block.blockType === 'hero') console.log(block.heading);
}Render blocks on your site
You write the components. Map each blockType to one:
<script lang="ts">
import Hero from './Hero.svelte';
import Cta from './Cta.svelte';
let { blocks } = $props();
</script>
{#each blocks as block (block.id)}
{#if block.blockType === 'hero'}
<Hero {block} />
{:else if block.blockType === 'cta'}
<Cta {block} />
{/if}
{/each}The website template does this with seven blocks. To add one, define it with block(), add a component, add a branch in RenderBlocks.svelte and register a preview in src/kitcms.admin.ts.
Preview blocks in the admin
Preview components are registered per block slug in src/kitcms.admin.ts, not in the config. See Live preview.
Why blocks have no preview option in the config
The config is server code. A Svelte component is browser code, so previews live in a separate client-safe file.