# Blocks
A block list lets editors build a page from sections: add a hero, then a
feature grid, then testimonials, and reorder them. In the schema it is an
array of a discriminated union keyed on `type`. AstroAdmin shows it as a list
of blocks with an "Add block" menu, one form per block, and drag to reorder.
## Schema
```typescript
// src/content.config.ts
import { defineCollection } from 'astro:content';
import { glob, file } from 'astro/loaders';
import { z } from 'astro/zod';
const blocks = z.discriminatedUnion('type', [
z.object({
type: z.literal('hero'),
heading: z.string(),
subheading: z.string().optional(),
image: z.string().optional(),
imageAlt: z.string().optional(),
}),
z.object({
type: z.literal('features'),
heading: z.string().optional(),
items: z.array(z.object({
title: z.string(),
description: z.string(),
})).default([]),
}).meta({ title: 'Feature grid' }),
z.object({
type: z.literal('testimonials'),
heading: z.string().optional(),
testimonialIds: z.array(z.string()).default([]),
}),
]);
const pages = defineCollection({
loader: glob({ pattern: '**/*.md', base: './src/content/pages' }),
schema: z.object({
title: z.string(),
blocks: z.array(blocks).default([]),
}),
});
const testimonials = defineCollection({
loader: file('src/content/testimonials.json'),
schema: z.object({
id: z.string(),
quote: z.string(),
author: z.string(),
}),
});
export const collections = { pages, testimonials };
```
The fields inside each block get the same controls as anywhere else (see
[schemas and controls](./content-collections.md)). The `type` literal is not
shown; it is set when the block is added. The block's label in the editor
comes from its type, so `sectionHeader` is shown as "Section header", unless
the block's object sets a title with `.meta({ title: '...' })`, as
`features` does above.
An entry, `src/content/pages/home.md`:
```markdown
---
title: Home
blocks:
- type: hero
heading: Build something
subheading: Start here.
- type: features
heading: Why us
items:
- title: Fast
description: Pages are static HTML.
- title: Simple
description: Content lives in your repository.
- type: testimonials
heading: What people say
testimonialIds:
- ada
---
```
## Components
Put one component per block type in `src/components/blocks/`, named after
the type with a `Block` suffix: `hero` is `HeroBlock.astro`, `testimonials`
is `TestimonialsBlock.astro`. Each takes the block as a `block` prop. The
integration's component preview (below) finds components by that name
(`Hero.astro` also works, and case and punctuation are ignored, so
`feature-grid` finds `FeatureGridBlock.astro`); a page can render the
components any way it likes.
```astro
---
// src/components/blocks/HeroBlock.astro
const { block, index } = Astro.props;
---
{block.heading}
{block.subheading && {block.subheading}
}
{block.image &&
}
```
```astro
---
// src/components/blocks/TestimonialsBlock.astro
import { getEntries } from 'astro:content';
const { block, index } = Astro.props;
const quotes = await getEntries(
block.testimonialIds.map((id) => ({ collection: 'testimonials', id })),
);
---
{block.heading && {block.heading}
}
{quotes.map((quote) => (
{quote.data.quote}
{quote.data.author}
))}
```
The page maps each block to its component:
```astro
---
// src/pages/index.astro
import { getEntry } from 'astro:content';
import HeroBlock from '../components/blocks/HeroBlock.astro';
import FeaturesBlock from '../components/blocks/FeaturesBlock.astro';
import TestimonialsBlock from '../components/blocks/TestimonialsBlock.astro';
const components = {
hero: HeroBlock,
features: FeaturesBlock,
testimonials: TestimonialsBlock,
};
const page = await getEntry('pages', 'home');
---
{page.data.blocks.map((block, index) => {
const Block = components[block.type];
return ;
})}
```
`data-block-index` and `data-aa-field` are optional. With them, clicking a
block's header in the editor outlines that block in the preview, and
clicking its text in the preview opens the field.
[Click-to-edit](./inline-editing.md#click-to-edit-in-the-preview) has the
naming rules, and its [Arrays](./inline-editing.md#arrays) section shows how
to annotate the items of a `features` block.
## Previewing a collection that blocks use
`testimonials` has no page of its own. Because the `testimonials` block
refers to it through `testimonialIds` (a `reference()` list works the same
way), AstroAdmin can still preview an entry by rendering that block with
only that entry in it, at `/component-preview/testimonials/`. This
needs:
- the integration in `astro.config.mjs`:
```javascript
import { defineConfig } from 'astro/config';
import astroadmin from 'astroadmin/integration';
export default defineConfig({
integrations: [astroadmin()],
});
```
- the block component at `src/components/blocks/TestimonialsBlock.astro`,
reading `block.testimonialIds`.
The block the route renders holds only `type` and the reference field, set
to that one id: a list (`testimonialIds`, `z.array(reference(...))`) gets
`['']`, a single field gets the one value, `''` for a `testimonialId`
string and `{ collection, id }` for a `reference('testimonials')`, as the
build would give it. The component receives it as `block`, and also spread as
props (`Astro.props.testimonialIds`), with `index` 0, so it must cope with
the block's other fields being absent. If the site has
`src/styles/global.css`, the route loads it; any other styles must come from
the component itself.
The route exists only under `astro dev`, never in a production build. If
several block types refer to the same collection, the editor offers a choice
of which to preview. A collection with a page of its own is better served by
a [preview route](./configuration.md#preview), which takes precedence.