Field types

This reference documents all field types available in block and template schema definitions. Field types define the input controls that appear in the CMS admin panel. They also determine how the CMS stores each value and how templates access it in Liquid.

Define fields in the settings array of a {% schema %} tag (for blocks and templates), or in config/settings_schema.json (for theme-level settings).

Common properties

All field types share these base properties:

text

Category: Leaf Admin control: Single-line text input Template value: String

A single-line text input field.

Properties

Schema example

{
  "type": "text",
  "name": "heading",
  "label": "Heading",
  "required": true,
  "defaultValue": "Welcome"
}

Template access

<h2>{{ block.heading }}</h2>

textArea

Category: Leaf Admin control: Multi-line text input Template value: String

A multi-line text input field for longer text content. It does not support formatting. Use richText for formatted content instead.

Properties

Schema example

{
  "type": "textArea",
  "name": "summary",
  "label": "Summary text",
  "required": false,
  "defaultValue": ""
}

Template access

{% if block.summary != blank %}
  <p class="summary">{{ block.summary }}</p>
{% endif %}

Note: The type name is camelCase: textArea, not textarea. The validator normalizes textarea to textArea. The canonical form is camelCase.

email

Category: Leaf Admin control: Email input with format validation Template value: String

An email address input. The CMS validates that the value is a properly formatted email address.

Properties

Schema example

{
  "type": "email",
  "name": "contact_email",
  "label": "Contact email address",
  "required": true
}

Template access

<a href="mailto:{{ block.contact_email }}">{{ block.contact_email }}</a>

number

Category: Leaf Admin control: Numeric input Template value: Number

A numeric input field for integer or decimal values.

Properties

Schema example

{
  "type": "number",
  "name": "columns",
  "label": "Number of columns",
  "defaultValue": 3
}

Template access

<div class="grid grid--{{ block.columns }}-col">
  {% for item in block.items %}
    <div class="grid__item">{{ item.title }}</div>
  {% endfor %}
</div>

checkbox

Category: Leaf Admin control: Checkbox toggle Template value: Boolean (true or false)

The admin panel renders this field as a checkbox that stores a boolean value.

Properties

Schema example

{
  "type": "checkbox",
  "name": "show_background",
  "label": "Show background colour",
  "defaultValue": false
}

Template access

{% if block.show_background %}
  <section class="section section--with-bg" style="background-color: {{ block.background_color }};">
{% else %}
  <section class="section">
{% endif %}

color

Category: Leaf Admin control: Color picker Template value: String (hex color code)

A color picker that returns a hex color string (for example, #ff5733).

Properties

Schema example

{
  "type": "color",
  "name": "accent_color",
  "label": "Accent colour",
  "defaultValue": "#e94560"
}

Template access

<section style="border-left: 4px solid {{ block.accent_color }};">
  {{ block.content_html }}
</section>

date

Category: Leaf Admin control: Date picker Template value: String (ISO date format)

A date picker without a time component.

Properties

Schema example

{
  "type": "date",
  "name": "publish_date",
  "label": "Publish date"
}

Template access

{% if block.publish_date != blank %}
  <time datetime="{{ block.publish_date }}">
    {{ block.publish_date | date: "%d %B %Y" }}
  </time>
{% endif %}

dateTime

Category: Leaf Admin control: Date and time picker Template value: String (ISO datetime format)

A date and time picker.

Properties

Schema example

{
  "type": "dateTime",
  "name": "event_start",
  "label": "Event start time"
}

Template access

<time datetime="{{ block.event_start }}">
  {{ block.event_start | date: "%d %B %Y at %H:%M" }}
</time>

Note: The type name is camelCase: dateTime, not datetime. The validator normalizes datetime to dateTime. The canonical form is camelCase.

radio

Category: Leaf Admin control: Radio button group Template value: String (the selected option's value)

A single-selection field rendered as visible radio buttons. Use when there are few options and visibility of all choices is helpful.

Properties

Schema example

{
  "type": "radio",
  "name": "text_alignment",
  "label": "Text alignment",
  "options": [
    { "label": "Left", "value": "left" },
    { "label": "Centre", "value": "center" },
    { "label": "Right", "value": "right" }
  ],
  "defaultValue": "left"
}

Template access

<div class="text-block text-block--align-{{ block.text_alignment }}">
  {{ block.body_html }}
</div>

See also

• select

select

Category: Leaf Admin control: Dropdown select Template value: String (the selected option's value)

A single-selection dropdown field. Use when there are many options or screen space is limited.

Properties

Schema example

{
  "type": "select",
  "name": "layout_variant",
  "label": "Layout variant",
  "options": [
    { "label": "Full width", "value": "full-width" },
    { "label": "Contained", "value": "contained" },
    { "label": "Narrow", "value": "narrow" },
    { "label": "Split", "value": "split" }
  ],
  "defaultValue": "contained"
}

Template access

<section class="section section--{{ block.layout_variant }}">
  {{ block.content_html }}
</section>

See also

• radio

code

Category: Leaf Admin control: Code editor Template value: String

A code editor input with syntax highlighting. Suitable for embed codes, custom scripts, or structured data.

Properties

Schema example

{
  "type": "code",
  "name": "embed_code",
  "label": "Embed code"
}

Template access

{% if block.embed_code != blank %}
  <div class="embed-wrapper">
    {{ block.embed_code }}
  </div>
{% endif %}

json

Category: Leaf Admin control: JSON editor Template value: Object or Array (parsed JSON)

A raw JSON input field. The CMS stores the value and returns it as a parsed JSON structure.

Properties

Schema example

{
  "type": "json",
  "name": "chart_data",
  "label": "Chart data (JSON)",
  "defaultValue": { "labels": [], "values": [] }
}

Template access

{% if block.chart_data %}
  <div class="chart" data-config='{{ block.chart_data | json }}'>
  </div>
{% endif %}

richText

Category: Leaf Admin control: Rich text editor Template value: Boolean (field presence) + String (HTML)

A rich text editor. Basker flattens rich text fields into two template properties:

• field_name: a boolean marker that the field exists on the block. It is true whenever the field is present, even if the editor never filled it in.
• field_name_html: the rendered HTML string

Properties

Schema example

{
  "type": "richText",
  "name": "body",
  "label": "Body content",
  "required": true
}

Template access

{% if block.body_html != blank %}
  <div class="rich-text">
    {{ block.body_html }}
  </div>
{% endif %}

block.body is true whenever the field is present on the block, even if the editor never typed anything into it. It does not guard against empty output. To render only when there is actual content, check block.body_html instead.

Note: The type name is camelCase: richText, not richtext. The validator normalizes richtext to richText. The canonical form is camelCase.

relationship

Category: Relationship Admin control: Document selector Template value: Object (the related document, flattened)

A reference to another document in the CMS. Basker resolves the related document and exposes its public data as a nested object. A field with hasMany: true returns an array of related documents.

Properties

Schema example

{
  "type": "relationship",
  "name": "featured_event",
  "label": "Featured event",
  "relationTo": "events"
}

Template access

{% if block.featured_event %}
  <div class="featured-event">
    <h3>{{ block.featured_event.title }}</h3>
    {% if block.featured_event.image %}
      <img src="{{ block.featured_event.image | image_url: width: 600 }}" alt="{{ block.featured_event.image.alt }}">
    {% endif %}
    <a href="{{ block.featured_event.url }}">View event</a>
  </div>
{% endif %}

The related document exposes public fields used by the active template, such as title, slug, image, or url. Check for optional properties before rendering them.

upload

Category: Relationship Admin control: File upload / media selector Template value: Object (the media document)

A file or media upload reference. By default, the field relates to the media collection. Basker exposes the uploaded file's data (URL, dimensions, alt text) as a nested object.

Properties

Schema example

{
  "type": "upload",
  "name": "background_image",
  "label": "Background image"
}

With explicit collection:

{
  "type": "upload",
  "name": "programme_pdf",
  "label": "Programme PDF",
  "relationTo": "media"
}

Template access

{% if block.background_image %}
  <div
    class="hero-bg"
    style="background-image: url('{{ block.background_image | image_url: width: 1920 }}');"
  >
    <h2>{{ block.heading }}</h2>
  </div>
{% endif %}

For file downloads:

{% if block.programme_pdf %}
  <a href="{{ block.programme_pdf | file_url }}" download>
    Download Programme ({{ block.programme_pdf.filename }})
  </a>
{% endif %}

The media object includes properties like url, filename, alt, width, height, mimeType, and sizes (for predefined image variants).

array

Category: Container Admin control: Repeatable field group with add/remove/reorder controls Template value: Array of Objects

A repeatable group of fields. Each row contains a set of sub-fields and receives a unique ID. Use for lists of items like slides, features, testimonials, or links.

Properties

Schema example

{
  "type": "array",
  "name": "slides",
  "label": "Slides",
  "fields": [
    {
      "type": "upload",
      "name": "image",
      "label": "Slide image",
      "required": true
    },
    {
      "type": "text",
      "name": "caption",
      "label": "Caption"
    },
    {
      "type": "text",
      "name": "link",
      "label": "Link URL"
    }
  ]
}

Template access

{% if block.slides.size > 0 %}
  <div class="slider">
    {% for slide in block.slides %}
      <div class="slider__slide">
        <img src="{{ slide.image | image_url: width: 1200 }}" alt="{{ slide.caption | default: '' }}">
        {% if slide.caption != blank %}
          <p class="slider__caption">{{ slide.caption }}</p>
        {% endif %}
        {% if slide.link != blank %}
          <a href="{{ slide.link }}" class="slider__link">Learn more</a>
        {% endif %}
      </div>
    {% endfor %}
  </div>
{% endif %}

Each row in the array is an object with the sub-field values as properties. Sub-fields follow the same rules as top-level fields. Basker flattens rich text into _html pairs, unwraps relationships, and so on.

The recommended maximum nesting depth for arrays and groups is 4 levels. The local checker warns above 4 levels and reports an error above 6 levels. Upload validation warns above 4 levels.

group

Category: Container Admin control: Collapsible field group Template value: Object

A single group of fields. Unlike array, a group is not repeatable. It contains exactly one set of sub-fields. Use for logically related fields that should be visually grouped in the admin panel.

Properties

Schema example

{
  "type": "group",
  "name": "cta",
  "label": "Call to action",
  "fields": [
    {
      "type": "text",
      "name": "button_text",
      "label": "Button text",
      "defaultValue": "Learn more"
    },
    {
      "type": "text",
      "name": "button_url",
      "label": "Button URL",
      "required": true
    },
    {
      "type": "select",
      "name": "button_style",
      "label": "Button style",
      "options": [
        { "label": "Primary", "value": "primary" },
        { "label": "Secondary", "value": "secondary" },
        { "label": "Outline", "value": "outline" }
      ],
      "defaultValue": "primary"
    }
  ]
}

Template access

{% if block.cta.button_url != blank %}
  <a href="{{ block.cta.button_url }}" class="btn btn--{{ block.cta.button_style }}">
    {{ block.cta.button_text | default: "Learn more" }}
  </a>
{% endif %}

Access group properties using dot notation: block.group_name.field_name. Groups can contain any field type, including nested arrays or groups (up to the recommended maximum depth of 4).

Index

By name

• array: repeatable group of fields
• checkbox: boolean toggle
• code: code editor input
• color: color picker
• date: date picker
• dateTime: date and time picker
• email: email input with validation
• group: single group of fields
• json: raw JSON input
• number: numeric input
• radio: single selection from radio buttons
• relationship: reference to another document
• richText: rich text editor
• select: dropdown single selection
• text: single-line text input
• textArea: multi-line text input
• upload: file/media upload reference

By category

Leaf types

• text
• textArea
• email
• number
• checkbox
• color
• date
• dateTime
• radio
• select
• code
• json
• richText

Relationship types

• relationship
• upload

Container types

• array
• group

Related

• Liquid tags reference: the schema tag for defining block and template schemas
• Liquid filters reference: filters for working with field values in templates
• How to create custom blocks: using field types in block schemas
• How to create page templates: using field types in template schemas
• How to define theme-level settings: using field types in settings_schema.json