A structure is a predefined, custom template that determines what should populate an array or object input.
This article covers all the keys available for structure configuration. To learn more about structures, read our documentation on creating a structure.
This key defines which structures are available for Object inputs and Array inputs.
The following nested keys are available for each input inside _structures:
styleid_keyvalueshide_extra_inputsreorder_inputsremove_empty_inputsremove_extra_inputs
This key has no default.
Each key under the key _structures will have the following options:
Defines whether the items are shown to your editors in a select menu (select, default) or a modal pop up window (modal).
Defines what key should be used to detect which structure an item is. If this key is not found in the array item, a comparison of key names is used (default _type).
Defines what values are available when the add button is clicked. See reference below for available options.
Sets the behavior when editing existing structure values with inputs not present in the structure with remove_extra_inputs set to false. Defaults to false. Has no effect if remove_extra_inputs is true.
If true, non-structure inputs are hidden in the Data Editor.
If false, non-structure inputs are visible in the Data Editor.
Controls whether or not inputs are sorted to match the structure when editing existing structure values. Defaults to true.
Non-structure inputs are ordered after structure inputs if not removed with remove_extra_inputs.
Sets the behavior when saving structures with empty inputs. Defaults to false.
Requires that an id_key is configured for this structure, as otherwise removing inputs would impact how structure values are compared.
If true, empty inputs are removed before persisting the structure data to the source file.
If false, empty inputs are persisted in the source file.
Removed inputs are available for editing again provided they are in the matching structure definition. Inputs are considered empty if the value is null, undefined or ''.
Sets the behavior when editing existing structure values with inputs not present in the structure definition. Defaults to false.
If true, non-structure inputs are removed before the editor loads, and subsequently removed from the source file if saved.
If false, non-structure inputs are either hidden or visible in the editor depending on hide_extra_inputs, but still kept in the source file on save.
If any inputs conflict with structure (e.g. an object's title is a string and the structure's title is an object), the structure version takes priority.
Each array item in values will have the following options:
If set to true, this item will be considered the default type for this structure. If the type of a value within a structure cannot be inferred based on its id_key or matching fields, then it will fall back to this item.
If multiple items have default set to true, only the first item will be used.
An icon used when displaying the structure (defaults to either format_list_bulleted for items in arrays, or notes otherwise).
Path to an image in your source files used when displaying the structure. Can be either a source (has priority) or output path.
Used in the array interface to display what kind of items editors can add.
The preview definition to change how to display structures when choosing a new structure (both in the select and modal styles). This takes priority over preview when choosing a new structure, and does not affect structures added to the Data Editor.
All preview options are available.
See the preview options documentation for detailed information on setting this option.
The preview definition to change how to display structures in the Data Editor, and when choosing a new structure (both in the select and modal styles).
All preview options are available here, although only the following options are used in the Data Editor:
textsubtexticonimage
See the preview options documentation for detailed information on setting this option.
Shows large image/icon preview per structure item. Has no default. See preview for details.
preview.gallery.fitdefaults tocontain.preview.gallery.imagehas no default, falls back to the first top-level image-like data found.
Controls the icon shown on each structure item. Must match a Material Icon name. Has no default, falls back to icon.
If set to false, no icon is displayed.
If image is set, it will cover icon when loaded successfully.
Controls the image shown per structure item. Has no default.
If set to false, no image is displayed.
If no image is found, icon is displayed instead.
Shows a list of items that can contain an image, icon and text per structure item. Has no default. See preview for details.
Controls the supporting text per structure item. Defaults to the description key, then falls back to the first text-like value found.
If set to false, no subtext is displayed.
Subtext is hidden if text and subtext is the same. If there’s no text, subtext is used instead.
Changes how the snippet is displayed once it has been added. Defaults to card, must be one of inline, gallery, or card.
Controls the main text shown per structure item. Has no default, falls back to label.
If set to false, no text is displayed.
Used to group and filter items when selecting from a modal.
The actual value used when items are added after selection
Structures now support the new preview option. Read our migration guide if you are still using the old options: text_key, subtext_key, image_key, preview_image, description, and image_size.