Skip to content

Advanced Properties and Defaults#

Flex Components support two advanced configuration blocks in the flex.json file:

  • advanced_properties Optional fields that appear in the Advanced tab of the Page Builder UI
  • defaults Prepopulated values for both properties and advanced_properties

This guide explains how each of these sections works and how they are tied to property types.

advanced_properties#

The advanced_properties array allows you to define secondary, less frequently used inputs that appear under a separate Advanced tab in the Page Builder admin.

These fields behave identically to properties, but are shown separately to reduce UI clutter for most users.

Example: 

"advanced_properties": [
  {
    "code": "background_color",
    "prompt": "Background Color",
    "type": "color"
  },
  {
    "code": "max_width",
    "prompt": "Max Width",
    "type": "text"
  }
]

You can use any supported property type inside advanced_properties, including:

  • Basic types like text, color, checkbox
  • Group and list structures
  • textsettings

defaults#

The defaults section pre-fills values for the component when first added to a page. It uses the code from each property as the key and defines a default value (or object, depending on type).

There are two top-level keys in the defaults object:

  • defaults.properties — for main tab values (implicitly just defaults)
  • defaults.advanced.properties — for values in advanced_properties

Example 

"defaults": {
  "headline": {
    "value": "Welcome to Our Store"
  },
  "advanced": {
    "background_color": {
      "value": "#ffffff"
    }
  }
}

Defaults by Property Type#

Text/Basic Types#

"defaults": {
  "button_text": { "value": "Shop Now" },
  "show_button": { "value": 1 },
  "rating": { "value": "5" }
}

Image#

"defaults": {
  "main_image": {
    "image": "graphics/%STORE_ID%/default.jpg",
    "alt": "Placeholder Image"
  }
}

"defaults": {
  "cta_link": {
    "text": "Click Here",
    "url": "https://example.com",
    "target": "_blank",
    "type": "url"
  }
}

Product / Category#

"defaults": {
  "featured_product": {
    "code": "PROD123"
  },
  "featured_category": {
    "code": "CAT456"
  }
}

Group#

"defaults": {
  "promo": {
    "heading": { "value": "New Season" },
    "subheading": { "value": "Just Dropped" }
  }
}

List (Text)#

"defaults": {
  "features": {
    "children": [
      { "value": "Free Shipping" },
      { "value": "Easy Returns" }
    ]
  }
}

List of Groups#

"defaults": {
  "slides": {
    "children": [
      {
        "heading": { "value": "Slide One" },
        "group_image": {
          "image": "graphics/%STORE_ID%/slide1.jpg",
          "alt": "First Slide"
        }
      }
    ]
  }
}

Best Practices#

  • Always use the code value as the key in the defaults object
  • For nested groups or lists, mirror the flex.json structure exactly
  • Use advanced for advanced_properties defaults
  • Ensure image and link defaults use the correct object structure
  • Use %STORE_ID% for default asset paths so they import correctly

Summary#

  • advanced_properties provides a clean UI separation for optional fields
  • defaults improves usability with pre-filled content
  • Each property type requires a matching structure in defaults
  • Mirroring the shape of l.settings:instance helps ensure consistency

Next Steps#