Skip to content

button#

The button property type allows Page Builder users to select a button style and size from the Theme Editor’s predefined options. It aligns Flex Components with the store’s global button system, improving brand consistency and maintainability.

button Definition#

{
  "code": "button_theme",
  "prompt": "Button Theme",
  "supports_customization": true,
  "supports_legacy": true,
  "type": "button"
}

Supported Fields#

Field Type Required Description
type string Yes Must be "button"
code string Yes Unique key used in l.settings:instance
prompt string Yes Label shown in Page Builder
supports_legacy boolean No Enables fallback to legacy buttons if theme buttons are unavailable
supports_customization boolean No Allows customization of style properties like font, color, etc.
required boolean No Requires a valid button selection before saving
preview_property_selector string No Targets DOM node for preview binding
visibility_conditions object No Used for conditional display logic

Field Behavior: supports_legacy#

When supports_legacy is set to true, the component will allow fallback to legacy button configurations. This is useful when:

  • Migrating older components that used separate select or text fields for button styles.
  • The Theme Editor is not in use, or buttons have not yet been configured.

theme_mode#

The theme_mode setting can be added to the defaults so that legacy components will allow for Theme Editor integration.

If theme_mode is false, the system will attempt to use legacy fallback values if available. 

"defaults": {
  "button_theme": {
    "code": "primary",
    "size": "m",
    "theme_mode": true
  }
}

Field Behavior: supports_customization#

When supports_customization is true, Page Builder allows the user to override specific visual styles of the selected theme button. This includes:

  • font-size (with units)
  • font-family
  • font-weight
  • color
  • background-color
  • border (width, style, color)

These can be defined per state (normal, hover, disabled) and are stored in the customizations object. The default settings will be in styles, disabled settings will be in disabled_styles and hover settings are contained within hover_styles with their respective overwrites. There is also a breakpoint_styles object that will contain the layout styles that can be customized.

Render Customizations#

When customizations are set in PageBuilder a stylesheet member will be added to the l.settings:instance structure that will contain the CSS to overwrite the style. 

button_theme:stylesheet=.mm-theme-button-primary.mm-theme-button-primary__large.flex_d0cd998cfd3c80a23d7af01bd4a43e14:hover { color: #fc1111; }

l.settings:instance Structure#

When no theme is set:

:button_theme:theme_available=0
:button_theme:theme_mode=1

When a Button Theme and size are selected via PageBuilder:

:button_theme:classname=mm-theme-button-primary+mm-theme-button-primary__large+flex_d0cd998cfd3c80a23d7af01bd4a43e14
:button_theme:code=primary
:button_theme:customizations:breakpoint_styles:mobile:font_size:unit=px
:button_theme:customizations:breakpoint_styles:mobile:letter_spacing:unit=px
:button_theme:customizations:breakpoint_styles:mobile:line_height:unit=px
:button_theme:customizations:breakpoint_styles:mobile:overwrite_size_settings=1
:button_theme:customizations:breakpoint_styles:mobile:padding_bottom:unit=px
:button_theme:customizations:breakpoint_styles:mobile:padding_bottom:value=15
:button_theme:customizations:breakpoint_styles:mobile:padding_left:unit=px
:button_theme:customizations:breakpoint_styles:mobile:padding_left:value=28
:button_theme:customizations:breakpoint_styles:mobile:padding_right:unit=px
:button_theme:customizations:breakpoint_styles:mobile:padding_right:value=28
:button_theme:customizations:breakpoint_styles:mobile:padding_top:unit=px
:button_theme:customizations:breakpoint_styles:mobile:padding_top:value=15
:button_theme:customizations:breakpoint_styles:tablet:overwrite_size_settings=0
:button_theme:customizations:disabled_styles:overwrite_border=0
:button_theme:customizations:disabled_styles:overwrite_drop_shadow=0
:button_theme:customizations:disabled_styles:overwrite_fill_color=0
:button_theme:customizations:disabled_styles:overwrite_text_color=0
:button_theme:customizations:disabled_styles:overwrite_text_settings=0
:button_theme:customizations:hover_styles:color:value=%23fc1111
:button_theme:customizations:hover_styles:overwrite_border=0
:button_theme:customizations:hover_styles:overwrite_drop_shadow=0
:button_theme:customizations:hover_styles:overwrite_fill_color=0
:button_theme:customizations:hover_styles:overwrite_text_color=1
:button_theme:customizations:hover_styles:overwrite_text_settings=0
:button_theme:customizations:styles:border_bottom_width:unit=px
:button_theme:customizations:styles:border_bottom_width:value=1
:button_theme:customizations:styles:border_color:value=%23ff1111
:button_theme:customizations:styles:border_enabled:value=1
:button_theme:customizations:styles:border_left_width:unit=px
:button_theme:customizations:styles:border_left_width:value=1
:button_theme:customizations:styles:border_right_width:unit=px
:button_theme:customizations:styles:border_right_width:value=1
:button_theme:customizations:styles:border_style:value=solid
:button_theme:customizations:styles:border_top_width:unit=px
:button_theme:customizations:styles:border_top_width:value=1
:button_theme:customizations:styles:color:value=%23FFFFFF
:button_theme:customizations:styles:letter_spacing:unit=px
:button_theme:customizations:styles:letter_spacing:value=10
:button_theme:customizations:styles:line_height:unit=px
:button_theme:customizations:styles:overflow_wrap:value=normal
:button_theme:customizations:styles:overwrite_border=1
:button_theme:customizations:styles:overwrite_corner_radius=0
:button_theme:customizations:styles:overwrite_drop_shadow=0
:button_theme:customizations:styles:overwrite_fill_color=0
:button_theme:customizations:styles:overwrite_font=0
:button_theme:customizations:styles:overwrite_padding=0
:button_theme:customizations:styles:overwrite_text_color=1
:button_theme:customizations:styles:overwrite_text_settings=1
:button_theme:customizations:styles:text_transform:value=none
:button_theme:customizations:styles:text_underline_enabled:value=0
:button_theme:size=l
:button_theme:theme_available=1
:button_theme:theme_mode=1

Note

The customizations structure will depend on the themes setup in Theme Editor. The example uses the default Button Themes and is overriding the text color on the default state.

Template Usage#

<mvt:if expr="l.settings:instance:button_theme:theme_available">
  <mvt:if expr="NOT ISNULL l.settings:instance:button_theme:stylesheet">
    <template data-theme-stylesheet>
      &mvt:instance:button_theme:stylesheet;
    </template>
  </mvt:if>
</mvt:if>

JavaScript Access#

var instance = <mvt:eval expr="miva_json_encode( l.settings:instance, '' )" />;
var code = instance.button_theme.code;
var size = instance.button_theme.size;
var customizations = instance.button_theme.customizations;

console.log(code, size, customizations);

Best Practices#

  • Use supports_legacy: true when migrating older components.
  • Use supports_customization: true if you want to allow style overrides in Page Builder.
  • Validate that the button class matches available theme options.
  • Combine with preview_property_selector for live preview alignment.
  • Render stylesheet if customizations are set.