BizzPocket

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 only feature-card blocks (3 at most), and
    • a feature-card placed directly in the group, under the row.

Nothing in it fetches data or ships JavaScript.


1. Install the group

bash
bizzpocket add group

This 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

blocks/feature-card/feature-card.tsx
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>
  ),
});
blocks/feature-card/feature-card.css
[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:

blocks/feature-row/feature-row.tsx
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>
    ),
});
blocks/feature-row/feature-row.css
[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:

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:

bash
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. In render it is a ReactNode[], one element per saved child, in order. You place the children; you never get their props or data.
  • allow and max bind twice. The editor offers only those blocks, and the renderer skips a saved child that is not allowed and anything past max (and logs it). Here, a hero saved inside feature-row would not render.
  • Nesting. The feature-card inside feature-row inside group sits two levels below the top-level block. The limit is three; deeper children are not rendered.
  • Trait variables. The group's padding and colors traits set --bp-spacing-* and --bp-color-* on its wrapper; its CSS resets them to initial on each child, so a child sees only its own. Do the same in your own container if it has traits (feature-row has 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