Version: next

Section field types

Reference of the field types available in a section's schema, the editor control each one renders, and how to configure it.

Each editable field in a section's schema has a type that selects its editor control in the properties sidebar. This page lists every available type and how to configure it. See Create custom sections for how a schema fits into a section.

Every key in a section's schema mirrors a key in its defaultProps; your component then receives the edited values as props.

`checkbox`

A boolean on/off toggle.

{ type: "checkbox", label: "Show divider", default_value: false }

`color`

A color picker from the themed palette.

{ type: "color", label: "Text color", default_value: "#111827" }

`datasource`

A picker backed by a data source — a typed catalog entity (a category, a product…) resolved server-side by the active backend. The editor shows a searchable list of options and stores the selected entity's key (its id, or a product SKU). The entity itself is delivered to your component as dynamic data through a matching GraphQL field (see Dynamic sections).

{ type: "datasource", dataSource: "product", label: "Product", default_value: null }

dataSource names the source (for example category or product). The available sources depend on the backend; a source the backend does not implement yields an empty picker.

Sources per flavor

Source	Gezy	Magento 2	Magento 1
`category`	✅	✅	✅
`product`	✅	✅ (search: the configured engine, or Magento's native search fallback)	✅ (list: requires an active search engine)
`user`	✅	✅	✅

A source a flavor does not implement degrades quietly: the field resolves to null and the picker lists no option, without an error.

On Magento, the category picker lists the first three levels of the navigation tree, indented; a deeper category is not selectable, and the search term filters the loaded levels rather than querying the catalog again. The product picker is the other way round: it lists nothing until the contributor types a term, which is sent to the search backend.

The picker also accepts a key typed by hand (a SKU for product, an id for category), next to the list. Contributors who know their catalogue go straight to the key, and it is the way to contribute when the source returns no option at all. The key is applied with Enter, with the Apply button, or by leaving the field — never while typing, so a partial key is never stored. It is not verified against the backend: the section preview is the feedback, and a key that resolves to nothing renders the section's empty state.

On Magento 1 the product picker lists options only when a search engine (ElasticSearch, Algolia, Attraqt) is active: there is no native full-text product search to fall back on, so without an engine the list stays empty and contributing goes through the manual key. A product already picked still renders. Every other source, and the Category Products Grid section, work without an engine.

The picker is empty as well while the engine is down, on both Magento flavors: the search layer answers an error fallback instead of failing. When that happens the server logs a warning — The search engine answered its error fallback — so an empty picker can be told apart from a genuine "no result".

If the manual key is not enough for your project, register your own product source: the registry is a map where the last registration wins.

services.DI.get("cms").dataSources.register("product", myProductDataSource);

Register it from afterServerServicesInit, or from onServerServicesInit of an extension declared after cms() in the extensions array of front-commerce.config.ts. Hooks run in declaration order, so an extension declared before cms() would see its source overwritten by the CMS one.

`date`

A native date picker. The value is an ISO YYYY-MM-DD string.

{ type: "date", label: "Publication date", default_value: "" }

`image`

An image picker storing a source URL and alt text. It opens the built-in media library, where the content manager browses folders and picks or uploads an asset.

{ type: "image", label: "Illustration", default_value: { src: "", alt: "" } }

`link`

The same input as url, for internal or external links.

{ type: "link", label: "Button link", default_value: "/contact", attributes: { placeholder: "https://…" } }

`margin`

A spacing editor for the four margins (unit + lock to edit all sides at once).

{
  type: "margin",
  label: "Margin",
  default_value: { top: 0, right: 0, bottom: 0, left: 0, unit: "px", locked: true },
}

`media`

A media picker storing the selected file's URL as a plain string (no alt text). It opens the same media library as image.

{ type: "media", label: "Attachment", default_value: "", attributes: { placeholder: "https://…" } }

`number`

A numeric slider.

{ type: "number", label: "Columns", default_value: 3, attributes: { min: 1, max: 6, step: 1 } }

`padding`

The same spacing editor as margin, for paddings.

{
  type: "padding",
  label: "Padding",
  default_value: { top: 16, right: 16, bottom: 16, left: 16, unit: "px", locked: true },
}

`range`

The same slider as number, for a bounded range.

{ type: "range", label: "Opacity", default_value: 100, attributes: { min: 0, max: 100, step: 1 } }

`repeater`

A repeatable list of sub-items — use it for FAQs, testimonials, link lists, tabs, and any variable-length collection. Each item is an object edited through its own nested form, described by itemSchema (a schema made of the field types on this page). Your section receives the value as an array of those item objects.

{
  type: "repeater",
  label: "Links",
  itemLabel: "Link",
  default_value: [{ label: "", url: "", description: "" }],
  itemSchema: {
    label: { type: "text", label: "Label", default_value: "" },
    url: { type: "link", label: "URL", default_value: "" },
    description: { type: "text", label: "Description", default_value: "" },
  },
}

itemLabel (optional) names each entry in the editor (for example "Link 1"). Content managers can add, remove, and reorder items.

An itemSchema may also hold a datasource field, so each row picks one catalog entity — that is how a "list of products" section lets the content manager choose N products in their own order:

{
  type: "repeater",
  label: "Products",
  itemLabel: "Product",
  default_value: [],
  itemSchema: {
    sku: { type: "datasource", dataSource: "product", label: "Product", default_value: null },
  },
}

The editor preview resolves those keys like a top-level datasource field, so the section shows the same content in the editor as on the published page. Only the datasource keys of a row are sent for resolution: the editorial fields next to them never trigger a new request.

`rich_text`

A rich-text editor. The value is a TipTap document (JSONContent), not a plain string.

{ type: "rich_text", label: "Body", default_value: "" }

Alongside text formatting, the toolbar lets content managers add links, insert images from the media library, and build tables. Rendered headings get a slugified id, so they can serve as in-page anchor targets.

Render it in your section with the TiptapContent theme component — the same one the built-in sections use:

import TiptapContent from "theme/modules/CmsPage/sections/tiptapRenderer";

// `body` is the `rich_text` prop your section receives
<TiptapContent content={body} />;

It renders the document with the theme's own atoms (headings, paragraphs, links). Two ways to customise it:

per usage — pass its componentsMap prop to override how individual nodes or marks render (entries you omit fall back to DEFAULT_TIPTAP_COMPONENTS);
globally — override it like any theme component by shadowing theme/modules/CmsPage/sections/tiptapRenderer in your own theme, which also changes how the built-in sections render rich text.

`select`

A single choice among the options you provide.

{
  type: "select",
  label: "Alignment",
  default_value: "center",
  options: [
    { label: "Left", value: "left" },
    { label: "Center", value: "center" },
    { label: "Right", value: "right" },
  ],
}

By default, a select renders as a connected-pill ChoicePicker. For large option sets (past ~6–8 options), pills wrap and clutter the editor sidebar. Set attributes: { display: "dropdown" } to render a native <select> dropdown instead.

{
  type: "select",
  label: "Icon",
  default_value: "checkmark",
  attributes: { display: "dropdown" },
  options: [
    /* …10+ options… */
  ],
}

`text`

A single-line text input.

{ type: "text", label: "Heading", default_value: "Welcome", attributes: { placeholder: "Enter a heading" } }

`textarea`

A multi-line text input.

{ type: "textarea", label: "Summary", default_value: "", attributes: { placeholder: "Short summary…", rows: 4 } }

`title`

A structured heading editor (text, level, size, weight, alignment).

{
  type: "title",
  label: "Title",
  default_value: { text: "Section title", level: "h2", size: "text-4xl", weight: "font-bold", alignment: "center" },
}

`url`

A URL input.

{ type: "url", label: "Video URL", default_value: "", attributes: { placeholder: "https://…" } }

checkbox​

color​

datasource​

Sources per flavor​

date​

image​

link​

margin​

media​

number​

padding​

range​

repeater​

rich_text​

select​

text​

textarea​

title​

url​