> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avocadostudio.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Built-in Blocks

> Catalogue of the block types Avocado Studio ships out of the box — schemas, renderers, and field metadata included.

Avocado Studio ships with 20 ready-to-use block types covering hero sections, content layouts, conversion CTAs, media, and navigation chrome. They are defined in `packages/shared/src/blocks/` (schemas + field metadata) and rendered by `packages/blocks/src/blocks/` (React components + CSS).

<Tip>
  The fastest way to *see* every built-in block rendered with default props is the live catalogue at [avocadostudio.dev/components](https://avocadostudio.dev/components) — sidebar, viewport switcher, and a live prop editor included. The monorepo's own `apps/site` also serves it at `http://localhost:3000/catalogue` in dev. Example sites and scaffolded projects do not ship that route.
</Tip>

## When to use built-ins vs. your own components

<Note>
  **On a site that already exists, your own components are the blocks.** The built-ins are a starting catalogue for sites built from scratch — they are not the thing you are expected to rebuild your site out of. See [Custom blocks](/integration/custom-blocks).
</Note>

* **Bring your own** when you have an existing component library or design tokens to preserve — which is the usual case. Register the components you already ship and declare which of their props are content.
* **Use the built-ins** when you are scaffolding a new site and want a content model without designing one. They cover the common marketing and landing patterns and are fully wired into the AI planner, asset manager, and preview overlay.
* **Mix them.** Built-ins and your own blocks coexist in one manifest. List the built-ins you actually render in `blockTypes`, or the editor offers all of them — see [custom blocks](/integration/custom-blocks#offer-only-the-blocks-you-render).

## Catalogue

### Content

| Block | What it is |
| - | - |
| **Hero** | Full-width hero section with headline, subheading, CTA buttons, and image. |
| **Feature Grid** | Grid of feature cards with optional icon, title, and description. |
| **Card** | Single prominent card with a CTA. The `full-bleed` variant renders a background image with dark overlay and white text. The one built-in building block (`role: "element"`): the picker offers it apart from the sections. |
| **Card Grid** | Grid of cards, each with title, description, and CTA. |
| **Testimonials** | Grid of testimonial cards with quotes and authors. |
| **FAQ Accordion** | Expandable question-and-answer section. |
| **Stats** | Row of big numbers with labels (e.g. `10K+ Users`). Each row takes an optional `unit`, set smaller on the figure's baseline. |
| **Quote** | Pull quote or blockquote with optional author attribution and avatar. |
| **Rich Text** | Freeform text content with markdown-style formatting. |
| **Banner** | Full-width announcement or alert bar with optional CTA button. Supports preset variants or custom `backgroundColor`/`textColor`. |
| **Tabs** | Switchable tabbed content panels with rich text in each tab. |
| **Carousel** | Image/content slideshow with prev/next navigation and dot indicators. |
| **Table** | Data table with column headers, rows, and optional stripe styling. |

### Conversion

| Block | What it is |
| - | - |
| **CTA** | Centered promotional section with a primary and optional secondary button. |

### Media

| Block | What it is |
| - | - |
| **Gallery** | Image grid with configurable columns and optional captions. |
| **Video** | Video player — supports YouTube, Vimeo URLs, or direct video files (mp4, webm). Auto-detects source type. |
| **Embed** | Embed external content — Google Maps, social media posts, or a custom iframe. For video, prefer the **Video** block. |

### Layout

| Block | What it is |
| - | - |
| **Two Column** | Composite two-column layout with typed child components in each column. |

### Navigation (chrome)

These blocks are structurally pinned — they cannot be added, moved, or removed by the AI. Every page has exactly one of each, and they render as global chrome.

| Block | What it is |
| - | - |
| **Site Header** | Global site navigation bar with logo, site name, and nav links. |
| **Footer** | Multi-column footer with link groups and copyright. |

## Section background

Sixteen built-ins — all but `Hero`, `Banner`, `SiteHeader` and `Footer` — take a `tone` prop,
shown in the property panel as **Background**: `default` is the page ground,
`panel` the step in from it, `inverse` the full-bleed band. An unknown value
falls back to the page ground. Colours come from the theme's tokens, so a
theme restyles all three.

## Field types you'll see

Each block declares per-field metadata (`kind`) that drives editor UI, AI behavior, and inline editability:

| Kind | Editor UI | Inline editable |
| - | - | - |
| `text` | Text input (textarea when `multiline`) | Yes |
| `richtext` | Rich-text (Tiptap) editor | Yes |
| `html` | Document editor over a stored HTML string | No, by default |
| `url` | URL input | No |
| `link` | Link picker over the site's own pages | No |
| `file` | Document picker (PDFs and other non-image assets) | No |
| `image` | Asset Manager modal (Unsplash, AI generation, upload) | No |
| `imageAlt` | Text input paired with the image field | No |
| `enum` | Dropdown | No |
| `color` | Color picker | No |
| `number` | Number input | No |
| `boolean` | Toggle | No |
| `headingLevel` | Heading-level dropdown (`h1`–`h6`) | No |
| `reference` | Shows where it points; offers no control | No |
| `stringList` | A list of text rows | Items, in place |
| `imageList` | A list of `{ image, alt }` rows | No |

<Note>
  `reference` is deliberately read-only. A CMS reference is a pointer — Storyblok's `{ linktype, id, cached_url }`, a Contentful entry link, a Sanity reference — not an href. Flattening one to a string breaks renames and makes the publish diff report the field as changed forever, so the panel shows the target and refuses the edit rather than corrupting it.
</Note>

Four flags change what a field means rather than how it is drawn: `inlineEditable: false` says a string is not edited in place; `panelOnly` says nothing on the page draws it, which takes it out of the coverage denominator; `readOnly` shows a value that can never be changed here; and `internal: true` marks a prop the storage system owns (a Storyblok `_uid`, a Contentful `sys`) so no surface shows it to a person and no planner is told it exists.

See [Block System Architecture](/integration/block-system) for the full vocabulary and the lifecycle from definition to render, and [Coverage checks](/integration/coverage) for how the flags affect the numbers.

## Extending the set

<CardGroup cols={2}>
  <Card title="Register your own blocks" icon="layer-group" href="/integration/custom-blocks">
    Author blocks in your own repo from components you already have, and expose them through your manifest. This is the normal path.
  </Card>

  <Card title="Declare a CMS-backed model" icon="table" href="/integration/field-table">
    One field table derives the schema, the panel metadata, the projection out of your CMS and the merge back into it.
  </Card>
</CardGroup>

<Warning>
  If you register a block under a name a built-in already uses — a `Hero` of your own — yours wins, and the property panel takes your declared field metadata over Avocado's. That is deliberate, but a name collision is worth knowing about: run [`panelCoverage`](/integration/coverage), which reports it as `colliding_type`.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.