Structure
Structured data input, which stores data in a field as YAML.
The structure field makes it possible to add multiple complex entries to a field, which will be stored as YAML. A typical use case would be a list of addresses, team members or a restaurant menu.

Example
fields:
addresses:
label: Addresses
type: structure
fields:
street:
label: Street
type: text
zip:
label: ZIP
type: text
city:
label: City
type: text
Such a structure will be stored in the content file like this:
addresses:
-
street: Rue de WTF 17
zip: 1112
city: Monaco
-
street: 1212 Broadway
zip: 4321
city: New York
-
street: At the beach
zip: 9999
city: The capitol of the Bahamas
Field properties
Property | Type | Default | Description |
---|---|---|---|
columns |
array | [] |
Optional columns definition to only show selected fields in the structure table. |
default |
array | – | Set the default rows for the structure |
disabled |
bool | – | If |
duplicate |
bool | true |
Toggles duplicating rows for the structure |
empty |
– | The placeholder text if no items have been added yet |
|
fields *
|
array | – | Fields setup for the structure form. Works just like fields in regular forms. |
help |
– | Optional help text below the field |
|
label |
– | The field label can be set as string or associative array with translations |
|
limit |
int | – | The number of entries that will be displayed on a single page. Afterwards pagination kicks in. |
max |
int | – | Maximum allowed entries in the structure. Afterwards the "Add" button will be switched off. |
min |
int | – | Minimum required entries in the structure |
prepend |
bool | – | Toggles adding to the top or bottom of the list |
required |
bool | – | If |
sortBy |
string | – | Sorts the entries by the given field and order (i.e. |
sortable |
bool | – | Toggles drag & drop sorting |
translate |
bool | true |
If |
when |
– | Conditions when the field will be shown (since 3.1.0) |
|
width |
string | 1/1 |
The width of the field in the field grid. Available widths: |
Fields
You can define any number of fields and use the same field types listed:
Blocks
A visual editor for long-form text and modular pages
Checkboxes
A list of checkbox fields
Date
A date picker field
An email input field with validation
Files
A files select field that allows to select one or multiple related files
Gap
Layout field to create gaps in the field grid.
Headline
Creates a headline to group fields
Hidden
Creates a hidden field
Info
A plain HTML field for user instructions
Layout
A visual editor for complex multi-column layouts
Line
Draws a horizontal line to separate fields
List
A simple WYSIWYG editor field for ordered and unordered lists
Multiselect
A select field that allows you to select multiple options
Number
A number input field with validation
Pages
A pages select field that allows to select one or multiple related pages
Radio
A list of radio buttons
Range
A handy slider
Select
A simple selectbox field
Structure
Structured data input, which stores data in a field as YAML.
Tags
An interactive tags input field with autocompletion
Tel
A phone number input field
Text
A standard, single-line input field
Textarea
A textarea field, which auto-resizes and has built-in format buttons.
Time
A time picker field
Toggle
Yes/no or on/off toggle
Url
A URL input field with validation
Users
A user select field that allows to select one or multiple users
Writer
A simple WYSIWYG editor field for inline content with formats like bold, italic, etc.
Default values
You can set default values for structure fields which will prepopulate the field:
emails:
label: Emails
type: structure
default:
- email: bastian@getkirby.com
- email: lukas@getkirby.com
- email: nico@getkirby.com
- email: sonja@getkirby.com
fields:
email:
label: Email
type: email
Table columns
You can define the columns that are shown in the table. This is especially useful if you have a lot of fields in your structure and you don't want to show them all on first sight, but still keep them editable. Columns can also change the text alignment, set a custom width and define a before and after text that will be prepended or appended to the value.
Option | Value | Description |
---|---|---|
width |
1/2 , 1/3 , 1/4 , 2/3 , 3/4 (any fraction since v3.2.0) |
Set width of column |
align |
left , center , right |
Set text alignment |
before |
string |
Set text to prepend value |
after |
string |
Set text to append value |
Example
fields:
holidays:
type: structure
columns:
title:
width: 1/4
images:
width: 1/2
price:
width: 1/4
align: right
after: "USD"
fields:
title:
type: text
images:
type: files
description:
type: textarea
price:
type: number
3.2.0
Structure columns can be set to any fraction and will be automatically calculated into the right width.
fields:
mystructure:
label: Structure
type: structure
columns:
title:
width: 3/5
images:
width: 1/5
price:
width: 1/10
fields:
title:
label: A
type: text
images:
label: B
type: text
price:
label: C
type: text
Hide toggle field text in preview
3.3.0
When using toggle fields within structures, displaying the field's text in the preview can sometimes look cluttered. You can hide the text with the text
option in the columns' definition.
fields:
structure:
columns:
a:
text: false
b:
text: false
fields:
a:
type: toggle
b:
type: toggle
text: this is some long text
Preview of fields in the table
The structure field tries to create the best possible preview for the field in its table view. If you are using fields provided by a plugin in the structure field, the preview of these can be customized with a field preview extension.
How to use in templates/snippets
To access a structure field in your templates, you can use the yaml()
and toStructure()
methods.
Let's say we wanted to render the holidays
structure field example from above in a template:
<?php
// using the `toStructure()` method, we create a structure collection
$items = $page->holidays()->toStructure();
// we can then loop through the entries and render the individual fields
foreach ($items as $item): ?>
<h2><?= $item->title()->html() ?></h2>
<?php foreach ($item->images()->toFiles() as $image): ?>
<img src="<?= $image->crop(400)->url() ?>">
<?php endforeach ?>
<p><?= $item->price() ?></p>
<?php endforeach ?>