Skip to content

group#

The group property enables logical grouping of one or more nested properties in a collapsible UI block. Groups help organize related fields (e.g., typography, spacing, layout options), and optionally support being toggled on/off by the user via can_disable.

`group` Definition#

{
  "code": "text_settings",
  "prompt": "Text Settings",
  "type": "group",
  "can_disable": true,
  "properties": [
    {
      "code": "heading",
      "prompt": "Heading",
      "type": "text"
    },
    {
      "code": "heading_color",
      "prompt": "Heading Color",
      "type": "color"
    }
  ]
}

Supported Fields#

Field	Type	Required	Description
`code`	string	Yes	Unique identifier for the group.
`prompt`	string	Yes	Label shown in the admin UI.
`type`	string	Yes	Must be `"group"`.
`properties`	array	Yes	List of nested property definitions.
`can_disable`	boolean	No	If `true`, users can toggle the group on/off.
`preview_property_selector`	string	No	Used to target preview DOM nodes.
`visibility_conditions`	object	No	Used for conditional UI logic.

`l.settings:instance` Structure#

Groups are flattened into the instance object using the group’s code as a namespace. If can_disable: true, a settings.enabled flag is added.

:text_settings:settings:enabled=1
:text_settings:heading:value=Welcome to Our Store
:text_settings:heading_color:value=#000000

If can_disable is not present, the settings block will not exist.

Template Usage#

Accessing Grouped Fields#

<h2 style="color: &mvte:instance:text_settings:heading_color:value;">
  &mvte:instance:text_settings:heading:value;
</h2>

Conditional Rendering#

<mvt:if expr="l.settings:instance:text_settings:settings:enabled">
  <h2 style="color: &mvte:instance:text_settings:heading_color:value;">
    &mvte:instance:text_settings:heading:value;
  </h2>
</mvt:if>

JavaScript Access#

<script>
  const group = l.settings.instance.text_settings;
  if (!group.settings || group.settings.enabled) {
    console.log(group.heading.value);
    console.log(group.heading_color.value);
  }
</script>

`defaults` Definition#

To pre-fill group fields with defaults:

"defaults": {
  "text_settings": {
    "settings": {
      "enabled": true
    },
    "heading": {
      "value": "Default Heading"
    },
    "heading_color": {
      "value": "#333333"
    }
  }
}

Best Practices#

Use group to keep related properties organized.
Set can_disable if the group should be toggleable (e.g., style blocks).
Use settings.enabled in your template to conditionally render grouped content.
Keep code consistent and lowercase, especially when referencing from l.settings:instance.

Complete Example#

{
  "code": "style_group",
  "prompt": "Text Style Group",
  "type": "group",
  "can_disable": true,
  "properties": [
    {
      "code": "font_color",
      "prompt": "Font Color",
      "type": "color"
    },
    {
      "code": "font_size",
      "prompt": "Font Size",
      "type": "text",
      "text_type": "number",
      "label": "px"
    }
  ]
}

Output#

:style_group:settings:enabled=1
:style_group:font_color:value=#333333
:style_group:font_size:value=16

Template#

<mvt:if expr="l.settings:instance:style_group:settings:enabled">
  <p style="color: &mvte:instance:style_group:font_color:value; font-size: &mvte:instance:style_group:font_size:value;px;">
    Styled text here
  </p>
</mvt:if>