# Structure Structured data input, which stores data as YAML. **** - Read more: - Source: **** 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 ```yaml 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: ```yaml 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 ``` If you need to store a single object instead of a list of objects, take a look at the object field. ## Field properties
Name Type Default Description
batch bool false Whether to enable batch editing
columns array [ ] Optional columns definition to only show selected fields in the structure table.
default array null Set the default rows for the structure
disabled bool null If true, the field is no longer editable and will not be saved
duplicate bool true Toggles duplicating rows for the structure
empty mixed null 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 mixed null Optional help text below the field
label mixed null The field label can be set as string or associative array with translations
limit int null The number of entries that will be displayed on a single page. Afterwards pagination kicks in.
max int null Maximum allowed entries in the structure. Afterwards the "Add" button will be switched off.
min int null Minimum required entries in the structure
prepend bool null Toggles adding to the top or bottom of the list
required bool null If true, the field has to be filled in correctly to be saved.
sortBy string null Sorts the entries by the given field and order (i.e. title desc) Drag & drop is disabled in this case
sortable bool null Toggles drag & drop sorting
translate bool true If false, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.
when mixed null Conditions when the field will be shown (since 3.1.0)
width string '1/1' The width of the field in the field grid, e.g. 1/1, 1/2, 1/3, 1/4, 2/3, 3/4
## Fields You can define any number of fields and use the same field types listed: Each field value is stored like in a normal Kirby content file. This means that all field types are supported, however all of their values are converted to strings. For most fields there is no difference, but fields with structured data will *not* be nested inside the same YAML data structure. This ensures broad compatibility. ## Default values You can set default values for structure fields which will prepopulate the field: ```yaml fields: 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`| any fraction, e.g. `1/2`, `1/3`, `1/4`, `2/3`, `3/4` | 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 | `mobile` | `true` | Set visible in mobile view ### Example ```yaml 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 ``` Structure columns can be set to any fraction and will be automatically calculated into the right width. ```yaml 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 ``` You can also define columns without additional options if you want to use the defaults. You can still combine this with options for other columns: ```yaml fields: holidays: type: structure columns: title: true images: true price: align: right after: "USD" fields: title: type: text images: type: files description: type: textarea price: type: number ``` ### Hide toggle field text in preview 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. ```yaml fields: structure: columns: a: text: false b: text: false fields: a: type: toggle b: type: toggle text: this is some long text ``` ### Set columns to visible on mobile The `mobile` option keeps cells in responsive views. If none of the columns are set to `mobile`, only the first column will be visible on mobile. ```yaml fields: structure: columns: image: type: image title: type: text mobile: true date: type: date mobile: true fields: image: type: files title: type: text date: type: date ``` ## 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. ## Batch delete You can activate the batch delete mode for structure fields by using the `batch` option in your blueprint: ```yaml fields: structure: batch: true ``` ## How to use in templates/snippets To access a structure field in your templates, you can use the [`yaml()`](/docs/reference/templates/field-methods/yaml) and [`toStructure()`](/docs/reference/templates/field-methods/to-structure) methods. Let's say we wanted to render the `holidays` structure field example from above in a template: ```php holidays()->toStructure(); // we can then loop through the entries and render the individual fields foreach ($items as $item): ?>

title()->html() ?>

images()->toFiles() as $image): ?>

price() ?>

``` If you nest structure fields inside a structure field, you have to call the `toStructure()` method on the nested fields as well and then loop through the nested items like above. ## More information Structured field content