---
title: "Blocks"
description: "Every block a body holds, with its props and their JSON Schema."
---

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

# Blocks

A product's, a lesson's or an article's, a custom page's and the store's home's **body** is a layout of blocks, read as a JSON string in its `content`: through the customer API's [`GET /v1/stores/{store}/body`](/customer-api/reference/read-body) or `include=body`, and written through the merchant API. These pages are built from the same definition the API checks a body against, so they list every type and prop it takes.

The whole block schema, every type in one, is at [`https://docs.sherpo.io/overview/blocks/schema.json`](https://docs.sherpo.io/overview/blocks/schema.json) (JSON Schema draft 2020-12): each type's page names it for the blocks a block holds.

## Bodies

- A body is an object whose `blocks` is its list of blocks, in the order they show.
- A product's page opens with its columns: `aside` blocks, each holding the blocks of the main or the side column, followed by any other blocks.
- Every block has an `id`, unique within its body, its `type`, and optionally `hidden: true`, which hides it and every block it holds.
- A text (a `markdown` block's `content`, and the rich texts other blocks hold) may hold blocks too, as `<block type="…" props="…"></block>` elements whose props are a block's but its `type`, read back with their defaults filled in. See [Bodies and rich text](/customer-api/rich-text).
- A block naming a store file holds its id (`fileId`); the read lists the file under `files`. See [Files and media](/customer-api/files).
- Render a type you don't know as nothing: a body saved long ago may hold a type this reference doesn't list, and new types may be added.

## Types

Where each type sits: **Yes** in the body itself, **In a text** only inside the body's texts.

| Type | What it is | The store's home | A custom page | A product's page | An event's page | A portfolio's page | A lesson | An article |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| [`actions`](/overview/blocks/actions) | A row of link buttons. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`article-list`](/overview/blocks/article-list) | A product's articles or episodes, newest first, made for a blog's or a podcast's page. | No | No | Yes | Yes | Yes | No | No |
| [`article-search`](/overview/blocks/article-search) | A search and filters over a product's articles or episodes, made for a blog's or a podcast's page. | No | No | Yes | Yes | Yes | No | No |
| [`aside`](/overview/blocks/aside) | A column of a product's page: the main one, or the side one. | No | No | Yes | Yes | Yes | No | No |
| [`audio`](/overview/blocks/audio) | An audio file played with its waveform: a store file, or an external URL. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`background-image`](/overview/blocks/background-image) | An image the page's background takes while the blocks after it show. | Yes | Yes | Yes | Yes | Yes | No | Yes |
| [`card`](/overview/blocks/card) | A card holding blocks. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`carousel`](/overview/blocks/carousel) | A row of slides, one block each, scrolled sideways. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`contact`](/overview/blocks/contact) | Ways to reach the store. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`diagram`](/overview/blocks/diagram) | A diagram drawn from Mermaid source in the store's colors. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`download`](/overview/blocks/download) | A store file to download: a card, or with `inline` a link inside a sentence. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`event-date`](/overview/blocks/event-date) | An event's dates and times, each in its own time zone and the visitor's, with a link to add it to a calendar. On an event's page only. | No | No | No | Yes | No | No | No |
| [`event-details`](/overview/blocks/event-details) | One of the store's events, as a card with its next date, its place and a link to its page. | Yes | Yes | Yes | Yes | Yes | No | Yes |
| [`event-list`](/overview/blocks/event-list) | The store's upcoming events as cards, the next first, and past ones under them when asked. | Yes | Yes | Yes | Yes | Yes | No | Yes |
| [`event-location`](/overview/blocks/event-location) | An event's place: its venue and address, or how it is joined online. On an event's page only. | No | No | No | Yes | No | No | No |
| [`expandable`](/overview/blocks/expandable) | Blocks shown up to a set height, with a button to show the rest. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`faq`](/overview/blocks/faq) | Questions and their answers. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`formula`](/overview/blocks/formula) | A display formula, rendered as math. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`grid`](/overview/blocks/grid) | Blocks laid out in columns. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`grid-products`](/overview/blocks/grid-products) | The store's products, as cards in a grid. | Yes | Yes | Yes | Yes | Yes | No | Yes |
| [`hero`](/overview/blocks/hero) | The heading section that opens a page. | Yes | Yes | Yes | Yes | Yes | No | Yes |
| [`hr`](/overview/blocks/hr) | A horizontal rule. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`image`](/overview/blocks/image) | An image: a store file, or an external URL. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`line-products`](/overview/blocks/line-products) | The store's support products (tips, donations, calls), in a row. | Yes | Yes | Yes | Yes | Yes | No | Yes |
| [`logo-cloud`](/overview/blocks/logo-cloud) | A row of logos. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`map`](/overview/blocks/map) | A place on a map: the store's own map of the point, its name and address over it, and the map's credit. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`markdown`](/overview/blocks/markdown) | A rich text. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`portfolio-activity`](/overview/blocks/portfolio-activity) | A portfolio's trades and events. On a portfolio's page only. | No | No | No | No | Yes | No | No |
| [`portfolio-chart`](/overview/blocks/portfolio-chart) | A portfolio's performance chart. On a portfolio's page only. | No | No | No | No | Yes | No | No |
| [`portfolio-holdings`](/overview/blocks/portfolio-holdings) | A portfolio's holdings. On a portfolio's page only. | No | No | No | No | Yes | No | No |
| [`portfolio-stats`](/overview/blocks/portfolio-stats) | A portfolio's headline figures. On a portfolio's page only. | No | No | No | No | Yes | No | No |
| [`portfolio-watchlist`](/overview/blocks/portfolio-watchlist) | A portfolio's watchlist. On a portfolio's page only. | No | No | No | No | Yes | No | No |
| [`portfolio-weights`](/overview/blocks/portfolio-weights) | A portfolio's holdings by weight. On a portfolio's page only. | No | No | No | No | Yes | No | No |
| [`pricing`](/overview/blocks/pricing) | Plans side by side, with their prices and features. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`product-card`](/overview/blocks/product-card) | One of the store's products, as a card. | Yes | Yes | Yes | Yes | Yes | No | Yes |
| [`product-content`](/overview/blocks/product-content) | A product page's list of the files it gives. | No | No | Yes | Yes | Yes | No | No |
| [`product-description`](/overview/blocks/product-description) | A product's `description` text. | No | No | Yes | Yes | Yes | No | No |
| [`product-get`](/overview/blocks/product-get) | A product page's buying section: its prices and the button to get it. | No | No | Yes | Yes | Yes | No | No |
| [`product-pages`](/overview/blocks/product-pages) | A product page's list of its lessons, episodes or articles. | No | No | Yes | Yes | Yes | No | No |
| [`product-review`](/overview/blocks/product-review) | A product's reviews: their count and average rating. | No | No | Yes | Yes | Yes | No | No |
| [`product-summary`](/overview/blocks/product-summary) | What a product holds, counted: its lessons, videos, files and the like. | No | No | Yes | Yes | Yes | No | No |
| [`product-what-you-get`](/overview/blocks/product-what-you-get) | What a product gives, its `what_you_get` text. | No | No | Yes | Yes | Yes | No | No |
| [`products`](/overview/blocks/products) | The store's products, as cards in a grid. An older form of `grid-products`. | Yes | Yes | Yes | Yes | Yes | No | Yes |
| [`side-by-side`](/overview/blocks/side-by-side) | Two columns of blocks side by side. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`slideshow`](/overview/blocks/slideshow) | A PDF from the store's files shown a page at a time, as a lesson's slides are, with no download. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`spacer`](/overview/blocks/spacer) | Empty space between blocks. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`stats`](/overview/blocks/stats) | Figures with their labels. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`theme-aware`](/overview/blocks/theme-aware) | Blocks shown in light mode, and others in dark mode. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`timeline`](/overview/blocks/timeline) | Dated steps in order. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`titled-section`](/overview/blocks/titled-section) | A section of blocks under a heading. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`video`](/overview/blocks/video) | A video: a store file, or an external URL. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| [`youtube`](/overview/blocks/youtube) | A YouTube video. | Yes | Yes | Yes | Yes | Yes | Yes | Yes |

Source: https://docs.sherpo.io/overview/blocks/index.mdx
