Reference
The block library
Every block that ships: what it is for, its fields, and its style settings.
Thallo ships 54 block types. Two capabilities add more: Accounts adds four, Commerce adds eighteen — five shop blocks, nine fields for the product page and four blocks for the shop home and category pages. This page lists all of them, in the order the Blocks tab and Settings › Block Types show them.
How to read the tables
Each block type has a slug, and the slug names its template: a block of type hero renders
through templates/blocks/hero.twig. A theme overrides one by
shipping its own copy at themes/<name>/templates/blocks/<slug>.twig; every template it does not
ship keeps rendering through the default theme's.
Fields lists each field's name and type. The types are the content model's, described in
the field types. A field is optional unless
the table says required. A field of type blocks holds other blocks: that is the Holds
blocks column, which names the block types the picker offers inside it. That list is a picker
convenience, not a rule: a block of another type saved through the API is not rejected. The
exception is a slot the table marks only, where anything else is refused.
Style settings names what the block adds to the inspector's Style and Layout tabs beyond the four every starter has: Spacing, Visibility, Sizing in a parent layout and Motion. Four blocks have no Motion, because a visitor never watches them arrive: Tab, Accordion item, Spacer and Animated text. Style settings says what each setting does and what it becomes in CSS.
Categories lead with Layout, Content, Media and Items; any other category follows in alphabetical order, which is why Account, Advanced, Commerce and Fields come last. Within a category the admin puts the active blocks first and orders each part by label; that is the order used here.
Layout
| Block | What it is for | Fields | Holds blocks | Style settings adds |
|---|---|---|---|---|
Container (container) |
Free-form wrapper: background image or video, overlay, and layout. It is the one block whose job is to arrange its children. | element (enum: div, section, article, aside, header, footer), background_image (asset), background_video (asset), background_video_url (string), bg_size (enum: cover, contain, auto), bg_position (enum: center, top, bottom, left, right), overlay (enum: none, light, dark), overlay_opacity (enum: 25, 50, 75), content (blocks) |
content: any |
Width, Placement, Colours, Corners, Border, Shadow, Backdrop, Minimum height, Overflow; the Layout tab's Container section (Layout, Direction, Wrap, Distribute, Align, Columns, Gap, Content width, Gutter); Stagger children and Ken Burns |
Footer (footer) |
A footer bar: copyright, links and social, over an optional top band. | top (blocks), copyright (blocks), links (blocks), social (blocks) |
top: any; copyright: any; links: Links, Navigation; social: Social links |
Background, Text colour |
Navigation (navigation) |
Links from a navigation menu: you pick a menu, not the links. | menu (string, required — a menu's slug), orientation (enum: horizontal, vertical), align (enum: start, center, end), size (enum: sm, md, lg), variant (enum: pill, link), color (enum: primary, neutral), highlight (enum: none, underline, bar), submenu_layout (enum: dropdown, columns), submenu_icon (enum: chevron-down, chevron-right, plus, none), submenu_trigger (enum: hover, click), aria_label (string) |
— | Distribute |
Separator (separator) |
A horizontal rule, optionally with a centred label and icon. | label (string), type (enum: solid, dashed, dotted), size (enum: xs, sm, md, lg, xl), icon (string — a Lucide icon name) |
— | Border colour |
Spacer (spacer) |
Vertical breathing room. | size (enum: small, medium, large) |
— | — (no Motion) |
Style (style) |
Re-skins a group of blocks with a chosen accent and neutral. | accent (enum: inherit or one of the accent colours), neutral (enum: inherit, slate, gray, zinc, neutral, stone), content (blocks) |
content: any |
Shadow |
The Style block's accents are the site's own, listed in change how the site looks. Building a header or a footer out of these is the header and the footer; filling a Navigation block's menu is menus and navigation.
Content
| Block | What it is for | Fields | Holds blocks | Style settings adds |
|---|---|---|---|---|
Accordion (accordion) |
A stack of expandable question and answer items. | title (string), multiple (boolean), items (blocks) |
items: Accordion item |
— |
Animated text (animated_text) |
A heading with a reveal effect and an optional rotating word. | prefix (string), rotate_words (text — one alternative per line, at most five), suffix (string), effect (enum: fade, slide-up, blur), loop (boolean), interval (number, 0.5 to 10 seconds), tag (enum: h1, h2, h3, p), prefix_color / rotate_color / suffix_color (token, colour), prefix_size / rotate_size / suffix_size (enum: inherit, sm, lg, xl), prefix_bold / rotate_bold / suffix_bold (boolean), prefix_italic / rotate_italic / suffix_italic (boolean) |
— | Text alignment, Typography, Text colour (no Motion) |
Blog posts (blog_posts) |
Lists published entries as cards. The list is built when the page renders. | type (string — a content type's slug), limit (number, 1 to 12), order (enum: newest, oldest), category (string), columns (enum: 1, 2, 3, 4), variant (enum: outline, soft, subtle, ghost, naked), orientation (enum: vertical, horizontal) |
— | Width |
Button (button) |
A standalone action button. | label (string, required), url (string, required), variant (enum: solid, outline, soft, subtle, ghost, link), color (enum: primary, neutral), size (enum: xs, sm, md, lg, xl), leading_icon (string), trailing_icon (string), block (boolean — full width) |
— | Distribute, Corners, Colours, Typography, Shadow |
Call to action (cta) |
A call-to-action band with buttons. | title (string, required), description (text), variant (enum: solid, outline, soft, subtle, naked), orientation (enum: vertical, horizontal), reverse (boolean), links (blocks), links_align (enum: start, center, end) |
links: Button |
Width, Corners, Shadow, Colours, Border, Typography |
Card (card) |
A content card: icon, title, description and nested blocks. | icon (string), title (string), description (text), variant (enum: outline, solid, soft, subtle, ghost, naked), orientation (enum: vertical, horizontal), reverse (boolean), body (blocks) |
body: any |
Corners, Shadow, Colours, Border, Typography |
Carousel (carousel) |
A swipeable slider: each child block is a slide. | slides (blocks), slides_per_view (enum: 1, 2, 3), arrows (boolean), dots (boolean), autoplay (boolean), style (enum: default, hero), transition (enum: slide, fade, zoom), speed (enum: slow, normal, fast), height (enum: compact, standard, tall, full) |
slides: any |
Width, Corners, Shadow |
Code (code) |
A code snippet with a language label and a copy button. | code (text, required), language (enum: text, bash, php, json, yaml, html, css, javascript, typescript, twig, sql), label (string), copy (boolean), size (enum: default, compact), note (string) |
— | Width, Corners, Shadow |
Collapsible (collapsible) |
A single show/hide disclosure wrapping nested blocks. | label (string), open (boolean), content (blocks) |
content: any |
Corners, Background, Border |
Color mode (color_mode) |
A light / system / dark colour-mode switch for visitors. | none | — | Distribute |
Form (form) |
A contact form: stores submissions and emails a recipient. | form_name (string), recipient (string), delivery (enum: store_and_email, email_only), success_message (text), redirect_url (string), submit_label (string), submit_variant (enum: solid, outline, soft, subtle, ghost, link), submit_color (enum: primary, neutral), heading (string), intro (text), name_label (string), email_label (string), message_label (string), include_subject (boolean), subject_label (string), include_phone (boolean), phone_label (string), phone_required (boolean), include_consent (boolean), consent_text (string) |
— | Width, Corners, Background, Border, Shadow |
Heading (heading) |
A single heading or label line. | text (string, required), level (enum: h1, h2, h3, h4, h5, h6) |
— | Width, Placement, Text alignment, Typography, Text colour |
Hero (hero) |
Big heading, supporting copy, buttons and media. | headline (string), title (string, required), description (text), links (blocks), image (asset), aside (blocks), orientation (enum: vertical, horizontal), split (enum: equal, copy, media), reverse (boolean), background (enum: gradient, none, muted, inverted), gradient_color (enum: accent or one of the accent colours), gradient_strength (enum: subtle, medium, strong), heading_level (enum: h1, h2, h3) |
links: Button; aside: any |
Width, Background, Text colour, Typography, Corners, Shadow, Aside; Ken Burns |
Links (links) |
A vertical list of navigation links with an optional title. | title (string), items (json — an array of objects with label, url, and optionally icon, active and new_tab) |
— | Title: Typography, Text colour, Text alignment; each link (its Link section): Typography, Text colour, Padding |
Pricing plan (pricing_plan) |
A single pricing plan card: price, features and a call to action. | title (string), description (text), price (string), discount (string), billing_period (string), billing_cycle (string), badge (string), features (text), feature_icon (string), tagline (string), terms (text), button_label (string), button_url (string), plan_key (string), button_variant (enum: solid, outline), variant (enum: outline, solid, soft, subtle), highlight (boolean), orientation (enum: vertical, horizontal) |
— | Corners, Shadow, Colours, Border |
Pricing plans (pricing_plans) |
A row or stack of pricing plans, with an optional featured plan. | plans (blocks), orientation (enum: horizontal, vertical), compact (boolean), scale (boolean) |
plans: Pricing plan |
Width |
Pricing table (pricing_table) |
A feature-comparison table across pricing tiers. | tiers (blocks), features (blocks), highlight (boolean) |
tiers: Pricing tier; features: Pricing feature |
Width |
Rich text (rich_text) |
Free-form formatted text. | body (text, rich) |
— | Width, Placement, Text alignment, Typography, Text colour |
Social links (social_links) |
A row of brand icons linking to social profiles. | items (blocks) |
items: Social link |
Distribute |
Stepper (stepper) |
A numbered sequence of steps, horizontal or vertical. | title (string), orientation (enum: vertical, horizontal), color (enum: primary, secondary, success, info, warning, error, neutral), size (enum: xs, sm, md, lg, xl), items (blocks) |
items: Stepper item |
— |
Tabs (tabs) |
Tabbed panels of blocks. | items (blocks), variant (enum: pill, underline, boxed), align (enum: start, center, end, stretch), list_background (enum: transparent, surface, surface-2, accent, text), tab_color (enum: accent, text, muted, accent-contrast, background), active_background (enum: transparent, surface, surface-2, accent, text, background), active_color (enum: accent, text, muted, accent-contrast, background), panel_padding (enum: none, sm, md, lg) |
items: Tab |
Colours, Corners, Border, Shadow, Tabs |
Setting a Form block up, including where its submissions go, is add a contact form. The Carousel's and the Animated text block's motion, and the Motion settings every other block has, are animate the page.
Media
| Block | What it is for | Fields | Holds blocks | Style settings adds |
|---|---|---|---|---|
Audio (audio) |
An uploaded audio file with the browser's own controls. | audio (asset, required), title (string) |
— | Width |
File (file) |
A download link to an uploaded file. | file (asset, required), label (string), new_tab (boolean) |
— | — |
Gallery (gallery) |
A responsive image grid with an optional lightbox. | items (blocks), columns (enum: 2, 3, 4), aspect (enum: natural, square, landscape), lightbox (boolean) |
items: Image only |
— |
Icon (icon) |
A single decorative icon from the Lucide set, optionally linked. | icon (string, required), size (enum: small, medium, large), align (enum: start, center, end), url (string), label (string) |
— | Text colour, Placement |
Image (image) |
A single image with a caption. | image (asset, required), alt (string), caption (string), width (number, px), height (number, px), fill (boolean) |
— | Width, Placement, Corners, Shadow |
Logo (logo) |
The site logo from Site › Appearance; falls back to the site name. | size (enum: small, medium, large), link_home (boolean) |
— | — |
Logos (logos) |
A "trusted by" strip of brand logos. | title (string), images (asset, several), grayscale (boolean), scroll (boolean) |
— | — |
Map (map) |
A Google map of your address, with directions. No API key: Google's own embed. | place (string), embed_url (string), zoom (number, 1–21), view (enum: map, satellite), height (enum: small, medium, large), directions (boolean), click_to_load (boolean), caption (string) |
— | Width, Corners, Border, Shadow |
Video (video) |
An uploaded video or a YouTube or Vimeo embed. | source (enum: upload, embed), video (asset), url (string), poster (asset), caption (string), width (enum: normal, wide, full) |
— | Width, Corners, Shadow |
Uploading the files these blocks point at is the media library.
Items
These are single-purpose children of the collection blocks above. Each one also has a template of its own, so a stray Accordion item outside an Accordion still renders.
| Block | What it is for | Fields | Holds blocks | Style settings adds |
|---|---|---|---|---|
Accordion item (accordion_item) |
One question with a rich-text answer. | question (string, required), answer (text, rich) |
— | — (no Motion) |
Feature (feature) |
One feature: icon or number, title, description, link. | icon (string), title (string, required), description (text), url (string), marker (enum: icon, number, none), number (string), marker_background (enum: transparent, surface, surface-2, accent, text), marker_color (enum: accent, text, muted, accent-contrast, background), marker_size (enum: sm, md, lg, xl), variant (enum: plain, outline, soft, subtle), orientation (enum: horizontal, vertical) |
— | Corners, Colours, Border, Shadow, Typography, Marker |
Pricing feature (pricing_feature) |
One comparison row, or a section heading, with a value per tier. | is_section (boolean), title (string), value_1 to value_4 (string) |
— | — |
Pricing tier (pricing_tier) |
One column of a pricing table: title, price and call to action. | title (string), description (text), price (string), discount (string), billing_period (string), billing_cycle (string), badge (string), button_label (string), button_url (string), button_variant (enum: solid, outline), highlight (boolean) |
— | — |
Social link (social_link) |
One social profile: brand icon and URL. | icon (string, required — a brand: icon name), url (string, required), label (string) |
— | Text colour |
Stepper item (stepper_item) |
One numbered step: title and description. | title (string, required), description (text) |
— | — |
Tab (tab) |
One tab: label and panel blocks. | label (string, required), content (blocks) |
content: any |
— (no Motion) |
Advanced
| Block | What it is for | Fields | Holds blocks | Style settings adds |
|---|---|---|---|---|
Shortcode (shortcode) |
Renders the theme's templates/shortcodes/<name>.twig. |
name (string, required), params (json, handed to that template as params) |
— | Colours, Border, Corners, Shadow |
HTML (html) |
Raw HTML, rendered verbatim. | code (text) |
— | — |
The HTML block ships deactivated: it is not in the Blocks tab until somebody turns it on in Settings › Block Types. Raw output is an explicit choice, not a default.
A Shortcode block's style settings land on whatever element the shortcode's own template puts them on, so a shortcode that ignores them renders as it always did. Writing one is part of make your own theme.
Account
Four blocks the Accounts capability (thallo.accounts) contributes. They are seeded while the
capability is on, and their rows disappear from Settings › Block Types while it is off —
nothing is deleted, and a page that already holds one keeps its data. Their style settings start
from Spacing and Visibility only: no Sizing in a parent layout, and no Motion.
| Block | What it is for | Fields | Holds blocks | Style settings adds |
|---|---|---|---|---|
Account state (auth-state) |
Shows one set of blocks to signed-out visitors and another to signed-in ones. | signed_out (blocks), signed_in (blocks) |
Both slots: Button, Links, Rich text, Logo, Navigation, Sign-in form, Registration form, Password reset request — only | — |
Password reset request (forgot-password-form) |
The request-a-reset-code form, embeddable on any page. Continues into the reset flow. | heading (string) |
— | Width, Corners, Background, Border, Shadow |
Registration form (register-form) |
The create-account form, embeddable on any page. Continues into the email-verification flow. | heading (string) |
— | Width, Corners, Background, Border, Shadow |
Sign-in form (login-form) |
The sign-in form, embeddable on any page. A failed attempt returns to this page with an inline error. | heading (string), next (string — where to go after signing in), show_links (boolean) |
— | Width, Corners, Background, Border, Shadow |
Which pages these compose, and what the capability turns on besides blocks, is let visitors have accounts.
Commerce
Five blocks the Commerce capability (thallo.commerce) contributes, on the same terms as the
Account blocks above: seeded while it is on, hidden while it is off, and starting from Spacing
and Visibility only.
| Block | What it is for | Fields | Holds blocks | Style settings adds |
|---|---|---|---|---|
Add to cart (add-to-cart) |
An add-to-cart control for a product. Left blank, it uses the product linked to the entry being rendered. With no product to use, the stage shows Add to cart — choose a product and the site hides it, as it does when a linked product is gone; a product chosen by slug that is gone reads as not available. Without JavaScript it is a link to the shop. |
product_slug (string) |
— | — |
Featured product (featured-product) |
Spotlight a single product. With no product set, the stage shows Featured product — choose a product and the site hides it, as it does for a product that is gone. Without JavaScript it is a link to the shop. |
product_slug (string) |
— | Corners, Shadow, Colours, Border |
Mini cart (mini-cart) |
A cart count and drawer that fills in over JavaScript; a plain cart link without it. | none | — | — |
Product grid (product-grid) |
A grid of products from a category, a tag, a manual list, or the newest arrivals. On the stage it names what it will show, such as Product grid — the newest products; the products appear on the published site. Without JavaScript it is a link to the shop, or to its category. |
source (enum: category, tag, manual, newest), category_slug (string), tag_slug (string), products (text — one product slug per line), page_size (enum: small, medium, large) |
— | Width |
Wishlist link (wishlist-link) |
A link to the wishlist page with a live saved-item count; a plain wishlist link without JavaScript. | label (string) |
— | — |
Turning Commerce on and connecting a shop is sell something.
Fields
Blocks for layouts, holding settings, never data. Nine show the current
entry's own data. Four more design a type's listing and archive
pages: the Entry list, the Listing
title, the Term description (archives only) and the Page navigation. Nine more, which the Commerce capability contributes, show the current
product on the product page's layout — seeded
while Commerce is on and hidden while it is off, like the Commerce blocks above. Four more, also
Commerce's, design the shop home and category
pages: the Product list, the
Product tile, the Shop title and the Category chips. They are offered
only in a layout's editor — each in its own kind of layout — and an entry, the header and footer
and a saved section refuse them when saved. A field an entry block names is a field of the
layout's content type; left empty, Entry cover, Entry excerpt and Entry terms show the
field named cover, excerpt or categories, and Entry content the type's body. Every
product layout holds exactly one Product buy box. It has no Visibility setting, and a
layout that hides a block holding it, at any size, is refused, as is an edit to a style class that
would make such a block hide it: no screen size loses the product page's buy button. Neither the
buy box nor a block holding it takes css_classes: a class name can be hidden by any stylesheet the
site loads.
Every listing and archive layout holds exactly one Entry list, under the same rules: no
Visibility, nothing around it may hide it, and neither it nor a block holding it takes
css_classes. Its card is the one post's design the list
repeats for every post on the page. Entry title, Entry date, Entry cover, Entry
excerpt, Entry terms and Entry field go inside the card on these pages, and only there;
the Entry list, the Listing title, the Term description and the Page navigation never go inside
it. A layout that breaks either rule is refused, naming the block.
Every shop home and category layout holds exactly one Product list, under the same rules. Its
card is the one product's design the list repeats for every product on the page. Product tile,
Product name, Product rating and Product price go inside the card on these pages, and
only there; inside a card the name, rating and price show as the shop's grid card shows them. The
Product list's cards are the shop's own grid — as many 15rem columns as fit — until its Layout tab
arranges them; the block type declares that grid, so the tab shows it as the theme's default.
| Block | What it is for | Fields | Holds blocks | Style settings adds |
|---|---|---|---|---|
Product buy box (product_buy) |
The product page's options, quantity and Add to cart button, with the wishlist heart and "In stock"; it works without JavaScript. Every product layout holds one. | hide_wishlist (boolean), hide_availability (boolean) |
— | Width (and no Visibility) |
Category chips (category_rail) |
"All" and a chip for every category, the page's own marked; nothing when the shop has no categories. | all_label (string) |
— | Width |
Entry content (entry_content) |
Where the entry's own content — its blocks field — goes. | field (string — a blocks field) |
— | Width |
Entry cover (entry_cover) |
An image field of the entry, such as its cover. | field (string — an asset field), aspect (enum: natural, 16:9, 4:3, 1:1), link (boolean) |
— | Width, Placement, Corners, Shadow |
Entry date (entry_date) |
When the entry was published. | format (enum: long, short, relative), prefix (string) |
— | Width, Placement, Text alignment, Typography, Text colour |
Entry excerpt (entry_excerpt) |
A short text field, shown as the lead. | field (string — a text field), clamp (number, 0 to 6 lines) |
— | Width, Placement, Text alignment, Typography, Text colour |
Entry field (entry_field) |
Any other field of the entry. | field (string), format (enum: text, rich, number, date) |
— | Width, Placement, Text alignment, Typography, Text colour |
Entry list (entry_loop) |
Every entry on a listing or archive page, each shown as the card you design once. Every listing and archive layout holds one. | card (blocks), empty_text (string) |
card: the entry's field blocks and any general block |
Width, on the list's own box, as its Spacing and Sizing in a parent layout; the Layout tab's arrangement of the cards (Layout, Direction, Wrap, Distribute, Align, Columns, Gap) (and no Visibility) |
Entry terms (entry_terms) |
A reference field's terms, such as its categories, linked to their archives where those pages exist. | field (string — a reference field), style (enum: text, badges), link (boolean) |
— | Width, Placement, Text alignment, Typography, Text colour |
Entry title (entry_title) |
The entry's title. | level (enum: h1, h2, h3, h4), link (boolean) |
— | Width, Placement, Text alignment, Typography, Text colour |
Listing title (listing_title) |
The list's title: the content type's name, or on an archive the term's title. | level (enum: h1, h2, h3, h4) |
— | Width, Placement, Text alignment, Typography, Text colour |
Page navigation (pagination) |
The newer and older pages of the list, and "Page X of Y"; nothing on a single page. | previous_label (string), next_label (string), count (boolean) |
— | Width, Placement, Text alignment, Typography, Text colour |
Previous and next (entry_neighbours) |
The published entries of the type either side of this one, by publish date. | previous_label (string), next_label (string) |
— | Width |
Product breadcrumb (product_breadcrumb) |
Shop, the product's category and its name. | hide_category (boolean) |
— | Width, Placement, Typography, Text colour |
Product category (product_category) |
The product's category, above its name. | link (boolean) |
— | Width, Placement, Text alignment, Typography, Text colour |
Product description (product_description) |
The product's description. | — | — | Width, Placement, Text alignment, Typography, Text colour |
Product gallery (product_gallery) |
The product's images: the cover, with thumbnails that swap it. | hide_thumbnails (boolean), aspect (enum: 4:3, 1:1, natural) |
— | Width, Corners, Shadow |
Product list (product_loop) |
Every product on a shop home or category page, each shown as the card you design once. Every shop layout holds one. | card (blocks), empty_text (string) |
card: the product's card blocks and any general block |
Width, on the list's own box, as its Spacing and Sizing in a parent layout; the Layout tab's arrangement of the cards (Layout, Direction, Wrap, Distribute, Align, Columns, Gap), the shop's adaptive grid by default (and no Visibility) |
Product name (product_name) |
The product's name; in a Product list card, the card's name. | level (enum: h1, h2, h3, h4), link (boolean) |
— | Width, Placement, Text alignment, Typography, Text colour |
Product price (product_price) |
The price, with the struck "was" price when there is one. Its size sets the amount's; the "was" price keeps to four fifths of it. | hide_compare_at (boolean) |
— | Width, Placement, Typography, Text colour |
Product rating (product_rating) |
The product's stars, average and review count; the stars grow with its size. | hide_when_none (boolean) |
— | Width, Placement, Typography, Text colour |
Product story (product_story) |
The content of the product's linked story. | — | — | Width |
Product tile (product_tile) |
A Product list card's picture, its category, and the quick Add to cart and wishlist buttons; the quick add works without JavaScript for a product with one variant. | hide_tag (boolean), hide_actions (boolean) |
— | Width |
Related entries (entry_related) |
The newest other entries of the type. | count (number, 1 to 6), style (enum: list, cards) |
— | Width |
Shop title (shop_title) |
"Shop", or the category's name, with the number of products beside it. | level (enum: h1, h2, h3, h4), hide_count (boolean) |
— | Width; Typography, Text colour and Text alignment on the heading |
Term description (term_description) |
An archive term's description. | — | — | Width, Placement, Text alignment, Typography, Text colour |
A layout's editor checks each field when the layout is applied and saved: Entry cover needs an asset field, Entry terms a reference field, Entry excerpt a text field, Entry content a blocks field, and Entry field any other scalar field.
Checking what an install has
The tables above are what Thallo ships. An install can hold more, because anyone can make a block type, and fewer in the picker, because any type can be switched off. Settings › Block Types is the list that install actually has: each card shows the label, the slug, the category and whether the type is active.
To add one of your own, see make your own block type. For what a block is and how its data is stored, see blocks and block types.