# Blocks

> Every built-in block in the language, with its form, content, own attributes and examples.

Blocks organize the content of a slide. There are two forms:

| Form | Syntax | Use |
| --- | --- | --- |
| Container | `::: name {attributes}` … `:::` | Blocks with content. A `:::` alone on a line closes the last open block. |
| Single line | `:: name value {attributes}` | Blocks without content, such as icons and spacers. |

Every block accepts the [style attributes](/docs/en/reference/attributes/#style-attributes). Container blocks can be nested freely, and indentation is optional.

## Summary

| Block | Form | Children | Own attributes |
| --- | --- | --- | --- |
| [`columns`](#columns) | Container | Each child is a column | `widths` |
| [`stack`](#stack) | Container | Stacked vertically | |
| [`row`](#row) | Container | Side by side, horizontally | `wrap` |
| [`grid`](#grid) | Container | Each child is a cell | `cols` |
| [`box`](#box) | Container | Stacked inside the box | |
| [`steps`](#steps) | Container | Revealed one at a time | |
| [`notes`](#notes) | Container | Plain text of the notes | |
| [`chart`](#chart) | Container | A table with the data | `type`, `legend`, `stacked`, `values`, `colors` |
| [`slot`](#slot) | Container | Content of a named slot | |
| [`icon`](#icon) | Single line | None; the value is the icon name | |
| [`spacer`](#spacer) | Single line | None; the value is the size | |
| [`divider`](#divider) | Single line | None | |

`icon`, `spacer` and `divider` do not accept content ([F109](/docs/en/reference/errors/)). On the other built-in blocks, text after the name is ignored ([F110](/docs/en/reference/errors/)); use attributes in braces.

## columns

Places its children side by side. **Each direct child is a column**: a paragraph, an image or, to group several elements in one column, a `::: stack`.

| Attribute | Values | Default |
| --- | --- | --- |
| `widths` | Proportions separated by spaces, one per column: `widths="2 1"` | Equal columns |
| `gap` | Space between columns | `md` (32 px) |
| `valign` | Vertical alignment of the columns | `center` |

```folio
::: columns {widths="2 1" gap=xl}
::: stack {gap=sm}
## Expansion plan
Two new regions by December,
with the same support team.
:::
::: box {.card align=center}
:: icon map-pin {color=accent}
2 regions
:::
:::
```

## stack

Stacks its children vertically. It is the block used to group several elements inside a column or a cell.

| Attribute | Use | Default |
| --- | --- | --- |
| `gap` | Space between children | `md` (32 px) |
| `align` | Horizontal alignment of the children | They take the full width |
| `valign` | Vertical alignment of the children | `top` |

```folio
::: stack {gap=xs align=center}
Chapter 1 {.kicker}
# Where it all began
A story in three acts {.muted}
:::
```

## row

Places its children in a horizontal line, each at the size of its own content. Useful for icons, badges and short lists of items.

| Attribute | Values | Default |
| --- | --- | --- |
| `wrap` | Boolean: wraps the items onto more lines when they do not fit | Off |
| `gap` | Space between items | 16 px |
| `align` | Horizontal distribution: `left`, `center`, `right` | `left` |
| `valign` | Vertical alignment of the items | `center` |

```folio
::: row {gap=md align=center}
:: icon star {size=lg color=yellow}
:: icon star {size=lg color=yellow}
:: icon star {size=lg color=yellow}
4.8 out of 5 from 1,200 reviews {size=xl}
:::
```

## grid

Grid with a fixed number of columns. Each child takes one cell, filling rows from left to right.

| Attribute | Values | Default |
| --- | --- | --- |
| `cols` | Number of columns, from 1 to 12 | Number of children, up to 3 |
| `gap` | Space between cells | `md` (32 px) |
| `valign` | Vertical alignment of the cells | Stretched to the same height |

```folio
::: grid {cols=3 gap=lg}
::: box {.card}
### Fast
Preview on every keystroke.
:::
::: box {.card}
### Consistent
Reusable themes and styles.
:::
::: box {.card}
### Versioned
History of every change.
:::
:::
```

## box

A box that stacks its children vertically and takes a background, border, corners and spacing. Combine it with the `.card` style (`bg=surface radius=lg pad=lg shadow=md`) or build the look with attributes.

| Attribute | Use | Default |
| --- | --- | --- |
| `gap` | Space between children | 20 px |
| `bg`, `border`, `radius`, `pad`, `shadow` | Look of the box | No background, no border |

```folio
::: columns {gap=lg}
::: box {.card}
### With `.card`
Background, corners and shadow included.
:::
::: box {border="3 accent" radius=md pad=lg}
### With attributes
Just a border and spacing.
:::
:::
```

## steps

Reveals its children one at a time during the presentation: each child is a step. If a child is a list, **each item** of the list becomes a step. In the preview and thumbnails, everything shows at once.

It accepts the same attributes as `stack`. To control the order by hand, use `{step=N}` on any block or span. See [Reveal](/docs/en/guides/reveal/).

```folio
## Three reasons
::: steps {gap=sm}
- Less time formatting
- More time on content
- Consistent presentations
:::
```

## notes

Speaker notes. The content does not show on the slide: it appears in [presenter view](/docs/en/guides/presenting/) and, in presentation mode, with the **N** key.

- The text is kept as is, without interpreting formatting or blocks.
- Several `notes` blocks on the same slide are joined, separated by a blank line.
- Attributes on the `::: notes` line are ignored.

```folio
# Results
We grew 38% this quarter.

::: notes
Pause after the number.
Ask if anyone has questions.
:::
```

## chart

Draws a chart from a Markdown table inside the block. The first column holds the labels; each following column is a series, and its header gives the series name. Cells accept numbers such as `42`, `3.5`, `3,5` and `12%`.

| Attribute | Values | Default |
| --- | --- | --- |
| `type` | `bar`, `line`, `area`, `pie`, `donut` | `bar` |
| `legend` | Boolean | On with more than one series or for `pie`/`donut` |
| `stacked` | Boolean: stacks the series | Off |
| `values` | Boolean: shows the values | Off |
| `colors` | Colors separated by spaces, one per series: `colors="accent blue"` | Theme palette |

```folio
::: chart {type=bar values}
| Month | 2025 | 2026 |
| --- | ---: | ---: |
| Jan | 32 | 41 |
| Feb | 28 | 45 |
| Mar | 35 | 52 |
:::
```

More examples in [Charts](/docs/en/guides/charts/).

## slot

Fills a named slot of a component. It can only be used directly inside the use of a container component ([F416](/docs/en/reference/errors/) anywhere else). The slot name goes after `slot`.

```folio
@component compare {before after}
::: columns {gap=xl}
::: box {.card}
### $before
$content
:::
::: box {.card}
### $after
$side-b
:::
:::
@end

::: compare {before=Spreadsheets after="Live dashboard"}
Export, paste and format by hand.
::: slot side-b
The data arrives on its own.
:::
:::
```

See [Components](/docs/en/guides/components/) for the details of `$content` and named slots.

## icon

Draws an icon from the built-in library. The name goes after `icon`; the full list is in [Icons](/docs/en/reference/icons/).

| Attribute | Use | Default |
| --- | --- | --- |
| `size` | Icon size: `xs`…`7xl` scale or pixels | 96 px |
| `color` | Stroke color | Text color |

```folio
::: row {gap=xl align=center}
:: icon rocket {size=3xl color=accent}
:: icon lightbulb {size=3xl color=yellow}
:: icon chart-line {size=3xl color=blue}
:::
```

## spacer

Empty space between two blocks. The value is a size from the [spacing scale](/docs/en/reference/attributes/#spacing) (`none` to `3xl`) or pixels from 0 to 600. With no value, it is `md` (32 px).

```folio
# Before the space
:: spacer 3xl
After 160 px {.muted}
```

## divider

Horizontal divider line. It accepts style attributes, such as `w` to limit its width and `opacity`.

```folio
## Section
:: divider {w=40%}
Text after the line {.muted}
```