Parameter examples

Common ways to declare a block's parameters and use them. Each example is a complete block definition; the rendering language has every type and attribute.

Basics

Text edited on the page

An element whose whole content is one @block.x of a text type is edited in place. The declaration's text is the default.

<section class="intro">
  <parameter name="heading" type="plain-text" required="true" max-length="60" display-text="Heading">Welcome</parameter>
  <h2>@block.heading</h2>
</section>

Formatted text

formatted-text allows bold, italic and links, nothing block-level. Use html only for free-form content (paragraphs, lists).

<section class="callout">
  <parameter name="message" type="formatted-text" max-length="200" toolbar="bold italic link" display-text="Message">Free shipping on <b>every</b> order.</parameter>
  <parameter name="body" type="html" display-text="Body"><p>Tell the whole story here.</p></parameter>
  <p class="lead">@block.message</p>
  <div class="body">@block.body</div>
</section>

An image

@block.photo is the image's address and @block.photo.alt its alt text.

<figure class="photo">
  <parameter name="photo" type="image" alt-required="true" aspect-ratio="4:3" display-text="Photo" />
  <img src="@block.photo" alt="@block.photo.alt" />
</figure>

A button or link

An anchor is a link with its text. A url is only the address, for when the text comes from elsewhere.

<div class="cta">
  <parameter name="button" type="anchor" display-text="Button">
    <anchor-parameter href="/contact" target="_self">Get in touch</anchor-parameter>
  </parameter>
  <parameter name="moreUrl" type="url" link-types="Page Article" display-text="Read more link" />
  <a class="btn btn-primary" href="@block.button.href" target="@block.button.target" data-link-id="@block.button.link-id">@block.button.text</a>
  <a href="@block.moreUrl">Read more</a>
</div>

A choice

A single-select's values are usually classes. The label is what editors see.

<section class="banner @block.tone">
  <parameter name="tone" type="single-select" default="banner-info" display-text="Tone">
    <option value="banner-info">Information</option>
    <option value="banner-success">Success</option>
    <option value="banner-warning">Warning</option>
  </parameter>
  <p>Heads up.</p>
</section>

Several choices

A multi-select joins the chosen values with a space, so it can add several classes.

<section class="panel @block.spacing">
  <parameter name="spacing" type="multi-select" editor="checkbox-list" display-text="Spacing">
    <option value="pt-0">No padding top</option>
    <option value="pb-0">No padding bottom</option>
    <option value="mb-5">Space below</option>
  </parameter>
  <p>Content</p>
</section>

On or off

A boolean is a switch. true-value and false-value are what it renders, often classes.

<section class="band @block.dark">
  <parameter name="dark" type="boolean" true-value="band-dark" false-value="band-light" default="band-light" display-text="Dark background" />
  <p>Content</p>
</section>

For an HTML attribute that's on when present (open, hidden), use attribute-boolean:

<details class="faq" open="@block.open">
  <parameter name="question" type="plain-text" display-text="Question">How do I start?</parameter>
  <parameter name="answer" type="formatted-text" display-text="Answer">Sign up and pick a template.</parameter>
  <parameter name="open" type="attribute-boolean" display-text="Start open" />
  <summary>@block.question</summary>
  <p>@block.answer</p>
</details>

Numbers, colors and dates

<section class="stats" style="--columns: @block.columns; background-color: @block.background">
  <parameter name="columns" type="integer" min="1" max="4" default="3" display-text="Columns" />
  <parameter name="background" type="color" palette="#ffffff, #f4f6fb, #0a3d62" default="#ffffff" display-text="Background" />
  <parameter name="updated" type="date" display-text="Updated on" />
  <p>Updated <time datetime="@block.updated">@block.updated</time></p>
</section>

Recipes

Optional text

Leave out an element when its parameter is empty.

<header class="section-head">
  <parameter name="eyebrow" type="plain-text" max-length="30" display-text="Eyebrow" />
  <parameter name="heading" type="plain-text" required="true" display-text="Heading">Our services</parameter>
  <if condition="not(empty(@block.eyebrow))">
    <p class="eyebrow">@block.eyebrow</p>
  </if>
  <h2>@block.heading</h2>
</header>

Fallback text

@coalesce takes the first value that isn't empty, so an empty field still shows something.

<a class="card-link" href="@block.link">
  <parameter name="link" type="url" required="true" display-text="Link" />
  <parameter name="linkText" type="plain-text" placeholder="Learn more" display-text="Link text" />
  @coalesce(@block.linkText, 'Learn more')
</a>

A section editors can turn off

<section class="feature">
  <parameter name="showButton" type="boolean" default="true" display-text="Show button" />
  <parameter name="button" type="anchor" visibility="eq(@block.showButton, 'true')" display-text="Button">
    <anchor-parameter href="/contact">Contact us</anchor-parameter>
  </parameter>
  <p>Content</p>
  <if condition="eq(@block.showButton, 'true')">
    <a class="btn" href="@block.button.href" target="@block.button.target">@block.button.text</a>
  </if>
</section>

visibility hides the Button field while the switch is off; the value is kept for when it's turned back on.

Layout variants

One single-select can switch between different markup.

<section class="media-block">
  <parameter name="layout" type="single-select" editor="segmented" default="stacked" display-text="Layout">
    <option value="stacked" icon="media-top">Image above</option>
    <option value="beside" icon="media-left">Image beside</option>
  </parameter>
  <parameter name="photo" type="image" alt-required="true" display-text="Photo" />
  <parameter name="text" type="formatted-text" display-text="Text">Say something about the photo.</parameter>
  <switch value="@block.layout">
    <case value="beside">
      <div class="row">
        <div class="col-md-5"><img class="img-fluid" src="@block.photo" alt="@block.photo.alt" /></div>
        <div class="col-md-7"><p>@block.text</p></div>
      </div>
    </case>
    <default>
      <img class="img-fluid" src="@block.photo" alt="@block.photo.alt" />
      <p>@block.text</p>
    </default>
  </switch>
</section>

Alignment buttons

editor="segmented" shows the options as buttons; an icon (see option icons) replaces the label, which becomes its tooltip.

<section class="intro @block.alignment">
  <parameter name="alignment" type="single-select" editor="segmented" default="text-start" display-text="Alignment">
    <option value="text-start" icon="align-left">Left</option>
    <option value="text-center" icon="align-center">Center</option>
    <option value="text-end" icon="align-right">Right</option>
  </parameter>
  <h2>Heading</h2>
</section>

A size per screen

A responsive-class-set chooses a class for each of the site's breakpoints (Settings > Breakpoints). Here they're mobile, tablet (768px) and desktop (1024px), which match Tailwind's md: and lg:. A screen left to inherit uses the smaller screen's choice.

<header class="page-head">
  <parameter name="headingSize" type="responsive-class-set" display-text="Heading size">
    <target name="mobile" default="m">
      <option key="s" value="text-2xl">S</option>
      <option key="m" value="text-3xl">M</option>
      <option key="l" value="text-4xl">L</option>
    </target>
    <target name="tablet" default="inherit">
      <option key="s" value="md:text-3xl">S</option>
      <option key="m" value="md:text-4xl">M</option>
      <option key="l" value="md:text-5xl">L</option>
    </target>
    <target name="desktop" default="l">
      <option key="s" value="lg:text-4xl">S</option>
      <option key="m" value="lg:text-5xl">M</option>
      <option key="l" value="lg:text-6xl">L</option>
    </target>
  </parameter>
  <h1 class="@block.headingSize font-bold">Heading</h1>
</header>

Keys are what's stored, so the classes can change later without changing pages.

An image per screen, with a focal point

targets asks for an image per screen. focal-point lets editors choose the part kept in view when the image is cropped.

<section class="hero">
  <parameter name="background" type="image" targets="desktop mobile" focal-point="true" display-text="Background" />
  <div class="hero-bg d-none d-md-block" style="background-image: url('@block.background.desktop')"></div>
  <div class="hero-bg d-md-none" style="background-image: url('@block.background.mobile')"></div>
</section>

Organizing a long form

Group related fields; a group can start collapsed. advanced="true" puts a field in the collapsed Advanced group.

<section class="promo">
  <parameter-group name="Text">
    <parameter name="heading" type="plain-text" display-text="Heading">Spring sale</parameter>
    <parameter name="subheading" type="plain-text" display-text="Subheading">This week only</parameter>
  </parameter-group>
  <parameter-group name="Style" expanded="false">
    <parameter name="tone" type="single-select" default="promo-light" display-text="Tone">
      <option value="promo-light">Light</option>
      <option value="promo-dark">Dark</option>
    </parameter>
  </parameter-group>
  <parameter name="trackingId" type="plain-text" advanced="true" display-text="Tracking ID" />
  <div class="@block.tone" data-tracking="@block.trackingId">
    <h2>@block.heading</h2>
    <p>@block.subheading</p>
  </div>
</section>

Suggested extra classes

Every block has extraClasses. Declaring it with options offers them as suggestions; editors can still type others.

<section class="content">
  <parameter name="extraClasses">
    <option value="pt-0">No padding top</option>
    <option value="pb-0">No padding bottom</option>
  </parameter>
  <p>Content</p>
</section>

The classes go on the root's class without any @block.extraClasses.

Passing a value to a child block

A parameter can fill a child block's parameter.

<section class="offer">
  <parameter name="buttonText" type="plain-text" display-text="Button text">Shop now</parameter>
  <h2>Offer</h2>
  <cta-button text="@block.buttonText"></cta-button>
</section>

Repeating items

Repeated content, like cards, goes in a slot that holds child blocks. Parameters set how it's laid out.

<section class="card-grid">
  <parameter name="columns" type="single-select" editor="segmented" default="row-cols-md-3" display-text="Columns">
    <option value="row-cols-md-2" icon="columns-2">Two</option>
    <option value="row-cols-md-3" icon="columns-3">Three</option>
    <option value="row-cols-md-4" icon="columns-4">Four</option>
  </parameter>
  <div class="row row-cols-1 @block.columns g-4">
    <slot name="cards"></slot>
  </div>
</section>