Skip to content

image#

The image property provides a file picker that allows users to select or upload an image through Miva’s Page Builder interface. It stores a reference to the image file path and supports responsive variants for mobile and tablet.

image Definition#

{
  "code": "hero_image",
  "prompt": "Hero Banner Image",
  "type": "image",
  "required": true,
  "width": 1600,
  "height": 600,
  "responsive_images": [
    {
      "code": "mobile",
      "prompt": "Mobile Image",
      "width": 375,
      "height": 320
    },
    {
      "code": "tablet",
      "prompt": "Tablet Image",
      "width": 768,
      "height": 480
    }
  ]
}

Supported Fields#

Field Type Required Description
code string Yes Unique key used in l.settings:instance.
prompt string Yes Label shown in the admin interface.
type string Yes Must be "image".
required boolean No If true, an image must be selected.
width number No Suggested image width for UI display.
height number No Suggested image height for UI display.
responsive_images array No List of device-specific image definitions.
preview_property_selector string No Used to target preview DOM nodes.
visibility_conditions object No Used for conditional UI logic.

Field Behavior: width & height#

These optional fields provide suggested dimensions for the image input field in the admin UI.

  • They are not enforced by Miva.
  • Their primary purpose is to communicate to the admin the ideal image dimensions for the component.
  • These values can be used in documentation, help text, or preview overlays, but they will not affect the uploaded image itself.

Example:

"width": 1600,
"height": 600

This suggests that the selected image should be 1600×600 pixels, but any image can still be used.

Field Behavior: responsive_images#

The responsive_images field enables multiple image slots, allowing the user to select alternate versions for mobile, tablet, or other contexts.

Each responsive image definition must include:

Field Type Required Description
code String Yes Identifier used in l.settings:instance
prompt String Yes Admin UI label for the image slot
width Number No Suggested width (for UI only)
height Number No Suggested height (for UI only)

Example:

"responsive_images": [
  {
    "code": "mobile",
    "prompt": "Mobile Image",
    "width": 375,
    "height": 320
  },
  {
    "code": "tablet",
    "prompt": "Tablet Image",
    "width": 768,
    "height": 480
  }
]

This creates additional image upload fields labeled “Mobile Image” and “Tablet Image” in the Page Builder interface.

Template Usage#

<img src="&mvte:instance:hero_image:value;" />
<img src="&mvte:instance:hero_image:mobile:value;" />
<img src="&mvte:instance:hero_image:tablet:value;" />

Use <picture> or media queries to load the appropriate image based on the user’s device.

Best Practice: Always define code and prompt for each responsive image. Add width/height if you want to provide guidance to content managers about image sizing.

l.settings:instance Structure#

:hero_image:value=graphics/00000001/hero.jpg
:hero_image:mobile:value=graphics/00000001/hero-mobile.jpg
:hero_image:tablet:value=graphics/00000001/hero-tablet.jpg

Each image variant (if defined) is stored by code.

Template Usage#

<picture>
  <source media="(max-width: 767px)" srcset="&mvte:instance:hero_image:mobile:value;">
  <source media="(max-width: 1023px)" srcset="&mvte:instance:hero_image:tablet:value;">
  <img src="&mvte:instance:hero_image:value;" alt="Hero">
</picture>

This ensures appropriate images load at different breakpoints.

JavaScript Access#

<script>
  const instance = <mvt:eval expr="miva_json_encode( l.settings:instance, '' )" />;
  const hero = instance.hero_image.value;
  const mobile = instance.hero_image.mobile.value;
  const tablet = instance.hero_image.tablet.value;
</script>

defaults Definition#

To set fallback images:

"defaults": {
  "hero_image": {
    "value": "graphics/%STORE_ID%/default-hero.jpg"
  }
}

You can also include mobile/tablet versions inside the defaults if needed.

Best Practices#

  • Always define a fallback image via defaults if image is optional.
  • Use responsive_images when breakpoints need separate assets.
  • Width and height fields are only hints for admin context — they do not resize or validate dimensions.
  • Use tokens like %STORE_ID% in default paths for portability.

Complete Example#

{
  "code": "banner_image",
  "prompt": "Banner Image",
  "type": "image",
  "required": true,
  "width": 1440,
  "height": 600,
  "responsive_images": [
    {
      "code": "mobile",
      "prompt": "Mobile Banner Image",
      "width": 375,
      "height": 320
    },
    {
      "code": "tablet",
      "prompt": "Tablet Banner Image",
      "width": 768,
      "height": 480
    }
  ]
}

Output#

:banner_image:value=graphics/00000001/banner.jpg

Template#

<img src="&mvte:instance:banner_image:value;" alt="Banner" width="100%">