Group layout with blocks inside
Put blocks inside blocks with the registry group and a container of your own (f.blocks()), and save the children in the layout JSON.
On this page
Goal: a home-page section that holds other blocks: the registry group lays them out, and a
container of your own (f.blocks()) accepts only feature cards, three at most.
The finished section is:
- a
group, page width, stacked, which holds- a
feature-row: your own container, which accepts onlyfeature-cardblocks (3 at most), and - a
feature-cardplaced directly in the group, under the row.
- a
Nothing in it fetches data or ships JavaScript.
1. Install the group
bizzpocket add groupThis copies blocks/group/group.tsx and blocks/group/group.css into your theme. You do not edit
them for this recipe. Their fields (layout, columns, gap, align, width, padding, colours, and
blocks: f.blocks({ max: 12 })) are listed in Container blocks.
2. The block that goes inside: feature-card
import { block, f, Link } from '@bizzpocket/theme';
import './feature-card.css';
export default block({
name: 'Feature card',
category: 'content',
description: 'A short title and sentence, with an optional link.',
fields: {
title: f.text({ default: 'Free returns' }),
text: f.text({ multiline: true, default: 'Changed your mind? Send it back within 30 days.' }),
linkLabel: f.text({ optional: true, label: 'Link text' }),
link: f.link({ label: 'Link' }),
},
render: ({ title, text, linkLabel, link }) => (
<div className="feature-card">
<h3 className="feature-card__title">{title}</h3>
<p className="feature-card__text">{text}</p>
{link && linkLabel ? (
<Link href={link} className="feature-card__link">
{linkLabel}
</Link>
) : null}
</div>
),
});[data-theme] .feature-card {
height: 100%;
box-sizing: border-box;
padding: 1.25rem;
border: 1px solid var(--color-border, rgba(0, 0, 0, 0.12));
border-radius: var(--radius-card, 0.75rem);
}
[data-theme] .feature-card__title {
margin: 0 0 0.5rem;
font-size: 1.125rem;
}
[data-theme] .feature-card__text {
margin: 0;
}
[data-theme] .feature-card__link {
display: inline-block;
margin-top: 0.75rem;
color: var(--color-primary, currentColor);
}3. A container of your own: feature-row
The registry group accepts any block. When a section should hold only one kind of block, write a
container with allow and max:
import { block, f } from '@bizzpocket/theme';
import './feature-row.css';
export default block({
name: 'Feature row',
category: 'content',
description: 'Up to three feature cards side by side, with a heading.',
fields: {
heading: f.text({ optional: true, default: 'Why shop with us' }),
// The editor offers only feature cards here, and at most three. The renderer enforces both too.
cards: f.blocks({ allow: ['feature-card'], max: 3, label: 'Cards' }),
},
render: ({ heading, cards }) =>
cards.length === 0 ? null : (
<div className="feature-row">
{heading ? <h2 className="feature-row__heading">{heading}</h2> : null}
<div className="feature-row__cards">{cards}</div>
</div>
),
});[data-theme] .feature-row__heading {
margin: 0 0 1rem;
}
[data-theme] .feature-row__cards {
display: grid;
grid-template-columns: minmax(0, 1fr);
gap: var(--spacing-s, 1rem);
}
@media (min-width: 48rem) {
[data-theme] .feature-row__cards {
grid-template-columns: repeat(3, minmax(0, 1fr));
}
}cards holds the children, already rendered, each in its own <section data-block-type="feature-card">.
The CSS styles the direct children of .feature-row__cards. It does not look inside them.
4. The layout JSON
The children are saved on the container's node, as children. A container node always has
children, even when it is empty. layouts/home.json:
{
"schemaVersion": 1,
"pageType": "home",
"pageIdentifier": "home",
"themeId": "my-theme",
"blocks": [
{
"id": "7a1c2e3f-4b5d-4c6e-8f70-81a2b3c4d5e6",
"type": "group",
"props": { "layout": "column", "width": "content", "gap": "l" },
"children": [
{
"id": "8b2d3f40-5c6e-4d7f-9081-92b3c4d5e6f7",
"type": "feature-row",
"props": { "heading": "Why shop with us" },
"children": [
{
"id": "9c3e4051-6d7f-4e80-a192-a3c4d5e6f708",
"type": "feature-card",
"props": { "title": "Free returns", "text": "Changed your mind? Send it back within 30 days." }
},
{
"id": "ad4f5162-7e80-4f91-b2a3-b4d5e6f70819",
"type": "feature-card",
"props": { "title": "Fast dispatch", "text": "Orders placed before 2 pm leave the same day." }
},
{
"id": "be506273-8f91-40a2-83b4-c5e6f708192a",
"type": "feature-card",
"props": { "title": "Cash on delivery", "text": "Pay when the parcel reaches you." }
}
]
},
{
"id": "cf617384-90a2-41b3-94c5-d6f708192a3b",
"type": "feature-card",
"props": {
"title": "Need help choosing?",
"text": "Write to us and a person answers within a day.",
"linkLabel": "Contact us",
"link": "/pages/contact"
}
}
]
}
]
}Replace my-theme with your theme's id. You do not have to write the ids by hand:
bizzpocket add-to-layout group # prints the group's id
bizzpocket add-to-layout feature-row --parent <group id> # prints the row's id
bizzpocket add-to-layout feature-card --parent <row id> # three times
bizzpocket add-to-layout feature-card --parent <group id>--parent refuses an id that is not in the layout, or a block that has no f.blocks() field.
How it works
f.blocks()is the only new field. Inrenderit is aReactNode[], one element per saved child, in order. You place the children; you never get their props or data.allowandmaxbind twice. The editor offers only those blocks, and the renderer skips a saved child that is not allowed and anything pastmax(and logs it). Here, aherosaved insidefeature-rowwould not render.- Nesting. The
feature-cardinsidefeature-rowinsidegroupsits two levels below the top-level block. The limit is three; deeper children are not rendered. - Trait variables. The group's
paddingandcolorstraits set--bp-spacing-*and--bp-color-*on its wrapper; its CSS resets them toinitialon each child, so a child sees only its own. Do the same in your own container if it has traits (feature-rowhas none). - Data. A child's
data()is collected with the rest of the page: a page with groups is still one data call, and a slow child streams in its own place inside the container.
JS cost
0 bytes. group, feature-row and feature-card are server HTML only (client gz 0, data
none in the size table). The cost is CSS: about 0.5 KB gzip for the group and a few hundred bytes
for the two blocks of this recipe.
Where the editor is today
Adding blocks inside a container in the seller editor, and the Next host rendering the children, are
still on the host change list (items 24 and 25 in Container blocks).
Until then, put children in the default layouts as above. The Bun runtime (bizzpocket dev) renders
them now.
See also
- Container blocks: every
f.blocks()option, whatrendergets, limits. - Fields: the other field kinds.
- Registry:
bizzpocket add.