Sections & settings

Sections are React components with a typed settings contract. The component exports a schema; the platform validates it at build time, and merchants edit the values in the Workspace theme editor — no code changes, no redeploys.

A section

app/sections/hero.tsx

import type { SectionSchema } from "@kotao/storefront-contracts";

export const schema: SectionSchema = {
  type: "hero",
  label: "Hero",
  settings: [
    { type: "text", name: "heading", label: "Heading", defaultValue: "Welcome" },
    { type: "richtext", name: "subheading", label: "Subheading" },
    { type: "image", name: "background", label: "Background image" },
  ],
};

export function Hero({ heading, subheading }: HeroProps) {
  /* … */
}

The schema mirrors the section’s entry in kotao.theme.json — the build’s validation gate checks both against SectionSchemaSchema from @kotao/storefront-contracts.

Setting input types

Simple values: text, textarea, richtext, number, boolean, color, color_scheme, date, font, url, link, file, video.

Structured values: range (min/max/step), select / radio / segmented (options), image (optional aspect ratio), and the commerce measurements dimension, weight, money (value + unit).

Reading values at runtime

Wrap the app in ThemeSettingsProvider and read with the hooks from @kotao/storefront/react:

• useThemeSettings() — global theme settings.
• useSectionSettings(sectionId) — one section instance’s values.
• useGlobalThemeTokens() — design tokens derived from settings.

Server-side, fetchThemeSettings / resolveThemeSettings (from @kotao/storefront/settings) load and merge the values document with your schema defaults.

Live preview

The Workspace editor talks to your theme through the editor bridge (@kotao/storefront/editor) — the scaffold wires it, so setting changes appear live in the preview without a reload.