Custom React sections

The storefront is React (Next.js), so a custom section is written exactly the way PlatformDTC’s own sections are: a React component with its settings schema in the same file. Once the file exists in your theme, the section is a section type like any other — templates reference it, the dashboard editor lists it in Add section, and merchants edit its settings in the sidebar.

File layout

theme/custom/sections/<type>.tsx    export const schema; export default function
theme/custom/blocks/<type>.tsx      export const schema; export default function

<type> is 1–48 characters of lowercase letters, digits and hyphens ([a-z0-9-]{1,48}), and must match the file name.
The section is registered as custom-<type>. theme/custom/sections/ingredient-grid.tsx becomes the section type custom-ingredient-grid. The prefix means a custom section can never collide with a platform section type, today or after a platform update.
You never register it by hand. On every preview compile and every publish, the pipeline generates theme/custom/index.ts from the files on disk and merges it into the section and block registries. Do not write theme/custom/index.ts yourself — it is regenerated.

What the file exports

Export	Type	Purpose
`schema`	`SectionSchema` (blocks: `BlockSchema`)	Name, settings, blocks, presets and placement rules. Drives the editor sidebar and validation.
`default`	a React component	Renders the section in the editor preview and on the live store.

The component receives the Builder2 render props:

Prop	Type	Meaning
`id`	`string`	This section’s id in the template (`"ingredients-1"`).
`settings`	`Record<string, unknown>`	Saved values keyed by each setting’s `id`. Values are `unknown` — a merchant, an agent or an older template may have stored anything, so read them defensively.
`blocks`	`{ id, instance }[]`	This section’s blocks, in order, with hidden blocks already removed. `instance.settings` holds each block’s values.
`sq`	`SqContext`	The runtime: `isEditing`, `renderBlocks()`, `editorRef`, `blockRef(blockId)`.

sq is what lets one component serve both the editor and the live store:

sq.editorRef — attach it to the section’s outermost element so clicking the section in the editor preview selects it. It is null in production.
sq.blockRef(blockId) — attach it to each block’s outermost element when the section renders its own blocks, so a click selects that block. Returns null in production.
sq.renderBlocks() — renders the section’s children when they are theme blocks (blocks registered with their own component) instead of section-local blocks.
sq.isEditing — true in the editor preview. Do not use it to show content a customer would not see; the preview should look like the store.

Settings

settings is an ordered list. Input settings carry an id and store a value; header and paragraph carry no id and only lay out the sidebar.

Types	Stored value
`text`, `textarea`, `richtext`, `inline_richtext`, `url`, `liquid`	string
`number`, `range` (`min`, `max`, `step`, `unit`)	number
`checkbox`	boolean
`select`, `radio` (`options: [{ value, label }]`)	string
`color`, `color_background`, `color_scheme`	string
`image_picker`	image URL string
`video`, `video_url` (`accept`)	string
`product`, `collection`	a reference to the product or collection — usually its handle; resolve it against the catalog from `useBuilder2Catalog()`
`page`, `blog`, `link_list`	handle string
`product_list` (`limit`)	an array of product references
`font_picker`, `style_preset`	string
`header`, `paragraph` (`content`)	none — sidebar only

Every input setting takes id, label, and optionally info (help text) and visible_if. Blocks come in two forms, the same two Shopify has:

{ "type": "text" } — a theme block, resolved from the block registry and rendered by its own component through sq.renderBlocks().
{ "type": "ingredient", "name": "Ingredient", "settings": [...] } — a section-local block. Its schema lives in the section, it has no component of its own, and your section renders it from blocks.

Presets make the section addable. A section with presets appears in the editor’s Add section picker. A section without presets can only be placed by writing template JSON, and the editor cannot remove it. Placement. enabled_on or disabled_on (use one, not both) take templates and groups. A section with neither is allowed on any page template but not in the header or footer groups; to allow a group, name it: enabled_on: { templates: ["*"], groups: ["footer"] }.

Imports

A custom section may import only:

Import	For
`react`	React itself and its types
`@/theme`	primitives (`StoreImage`, `Button`, `Price`, `ProductCard`…), hooks, the cart, and store data (`useBuilder2Catalog`, `useMenu`, `usePage`…)
`@/theme/builder2/types`	types only (`import type`): `SectionRenderProps`, `BlockRenderProps`, `SectionSchema`, `BlockSchema`, `SettingDef`
`@/lib/*`	the storefront’s library modules
other files under `theme/custom/`	your own shared components and helpers, by relative path

Anything else — including a new npm package — fails theme check with import-resolves. Import runtime values from the @/theme barrel rather than from a deeper path: @/theme is loaded once and shared by every page, while a deep path bundles a second copy into your page, and a second copy of a stateful module (the cart, the store data context) silently stops sharing state with the rest of the store. Type-only imports (import type) are removed at build time and cost nothing.

A complete example

theme/custom/sections/ingredient-grid.tsx — a grid of a product’s active ingredients, each with an optional image, the amount per serving and what it does. It uses section-local blocks, selects correctly in the editor, and renders nothing for anything the merchant has not filled in.

theme/custom/sections/ingredient-grid.tsx

"use client";

import type { JSX } from "react";
import { StoreImage, cn } from "@/theme";
import type { SectionRenderProps, SectionSchema } from "@/theme/builder2/types";

/** Stored setting values are `unknown`; read them defensively. */
function text(settings: Record<string, unknown> | undefined, key: string): string {
  const value = settings?.[key];
  return typeof value === "string" ? value.trim() : "";
}

const COLUMNS: Record<number, string> = {
  2: "sm:grid-cols-2",
  3: "sm:grid-cols-2 lg:grid-cols-3",
  4: "sm:grid-cols-2 lg:grid-cols-4",
};

export const schema: SectionSchema = {
  type: "custom-ingredient-grid",
  name: "Ingredient grid",
  category: "content",
  settings: [
    { id: "heading", label: "Heading", type: "text", default: "What's inside" },
    { id: "intro", label: "Introduction", type: "textarea", default: "" },
    { id: "columns", label: "Columns on desktop", type: "range", min: 2, max: 4, step: 1, default: 3 },
    { type: "header", content: "Appearance" },
    { id: "background", label: "Background", type: "color", default: "var(--sq-bg)" },
  ],
  blocks: [
    {
      type: "ingredient",
      name: "Ingredient",
      settings: [
        { id: "image", label: "Image", type: "image_picker" },
        { id: "name", label: "Ingredient", type: "text" },
        { id: "amount", label: "Amount per serving", type: "text", info: "For example 600 mg" },
        { id: "benefit", label: "What it does", type: "textarea" },
      ],
    },
  ],
  max_blocks: 12,
  presets: [{ name: "Ingredient grid", settings: { heading: "What's inside", columns: 3 } }],
};

export default function IngredientGrid({ settings, blocks, sq }: SectionRenderProps): JSX.Element | null {
  const heading = text(settings, "heading");
  const intro = text(settings, "intro");
  const background = text(settings, "background") || "var(--sq-bg)";
  const rawColumns = Number(settings.columns);
  const columns = Number.isFinite(rawColumns) ? Math.min(Math.max(Math.round(rawColumns), 2), 4) : 3;

  // An ingredient without a name has nothing to say: it is not rendered at all.
  const ingredients = blocks.filter((block) => text(block.instance.settings, "name") !== "");

  if (!heading && ingredients.length === 0) return null;

  return (
    <section
      ref={sq.editorRef ?? undefined}
      className="px-5 py-16 sm:px-8 lg:px-14"
      style={{ background }}
    >
      <div className="mx-auto max-w-6xl">
        {heading || intro ? (
          <header className="mb-10 text-center">
            {heading ? <h2 className="text-3xl font-black tracking-tight sm:text-4xl">{heading}</h2> : null}
            {intro ? <p className="mx-auto mt-3 max-w-2xl text-base opacity-70">{intro}</p> : null}
          </header>
        ) : null}

        {ingredients.length > 0 ? (
          <ul className={cn("grid grid-cols-1 gap-6", COLUMNS[columns])}>
            {ingredients.map((block) => {
              const image = text(block.instance.settings, "image");
              const name = text(block.instance.settings, "name");
              const amount = text(block.instance.settings, "amount");
              const benefit = text(block.instance.settings, "benefit");
              return (
                <li
                  key={block.id}
                  ref={sq.blockRef(block.id) ?? undefined}
                  className="flex flex-col gap-3 rounded-sq border border-sq-border p-5"
                >
                  {image ? (
                    <StoreImage
                      src={image}
                      alt={name}
                      sizes="(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw"
                      maxWidth={800}
                      className="aspect-square w-full rounded-sq object-cover"
                    />
                  ) : null}
                  <div className="flex items-baseline justify-between gap-3">
                    <h3 className="text-lg font-bold">{name}</h3>
                    {amount ? <span className="text-sm opacity-70">{amount}</span> : null}
                  </div>
                  {benefit ? <p className="text-sm leading-6 opacity-80">{benefit}</p> : null}
                </li>
              );
            })}
          </ul>
        ) : null}
      </div>
    </section>
  );
}

What this section does deliberately:

An empty value renders nothing. No image means no image element, not an empty grey box; an ingredient with no name is not listed; a section with no heading and no ingredients returns null. An empty framed square reads to a shopper as a photo that failed to load.
The preset has no sample ingredients. Sample copy added from the picker would go live the moment the theme is published. The merchant or the agent adds real ingredients.
Numbers from settings are clamped. columns is stored as unknown, so it is converted and kept between 2 and 4.
StoreImage, not <img> or next/image. It requests an image sized for the viewport and never preloads below-the-fold images.

Use it from templates/index.json:

templates/index.json

{
  "version": 2,
  "sections": {
    "hero": { "type": "hero", "settings": {} },
    "ingredients": {
      "type": "custom-ingredient-grid",
      "settings": { "heading": "What's inside", "columns": 4 },
      "blocks": {
        "ashwagandha": {
          "type": "ingredient",
          "settings": {
            "name": "Ashwagandha root extract",
            "amount": "600 mg",
            "benefit": "An adaptogen traditionally used to support a calm response to everyday stress."
          }
        },
        "magnesium": {
          "type": "ingredient",
          "settings": {
            "name": "Magnesium glycinate",
            "amount": "200 mg",
            "benefit": "Contributes to normal muscle function and to the reduction of tiredness and fatigue."
          }
        }
      },
      "block_order": ["ashwagandha", "magnesium"]
    }
  },
  "order": ["hero", "ingredients"]
}

Use your product’s real ingredients, amounts and claims — what a section says on the live store is a statement your business makes to customers.

Rendering safely

A section that throws does not take the page down. Each section renders inside its own error boundary and Suspense boundary, so a bug hides that one section. Still: check it in the preview.
Mark interactive sections "use client". Sections render in the browser and in the search-engine bake; a section that uses state or effects needs the directive.
Content should be in the HTML. Prefer native elements (<details> for an accordion) over state that hides content until JavaScript runs — the page is baked for search engines and fast first paint.
Styling. Use Tailwind classes. The theme’s tokens are available as classes such as bg-sq-surface, text-sq-fg, border-sq-border, rounded-sq and as CSS variables such as var(--sq-bg), so a section follows the store’s colours and radius. Theme-wide CSS goes in styles/merchant.css.

Custom blocks

A theme block in theme/custom/blocks/<type>.tsx follows the same pattern: export const schema (a BlockSchema: type, name, settings, optionally nested blocks and max_blocks) and a default component receiving { id, settings, blocks, sq }. It registers as custom-<type> in the block registry, and a section accepts it with blocks: [{ type: "custom-<type>" }] — or any registered block with { type: "@theme" }.

Check before you publish

Run theme check — dtc theme check locally, or the check_theme tool. TypeScript errors in changed custom files are warnings on a development theme and errors on publish, so a section that does not type-check cannot go live.

Build with your agent

Theme reference

Custom React sections

File layout

What the file exports

Settings

Imports

A complete example

Rendering safely

Custom blocks

Check before you publish

​File layout

​What the file exports

​Settings

​Imports

​A complete example

​Rendering safely

​Custom blocks

​Check before you publish

File layout

What the file exports

Settings

Imports

A complete example

Rendering safely

Custom blocks

Check before you publish