Variant Metafield Media

Shows the image or video stored in a variant-level Shopify file metafield for the selected variant.

Last updated

August 14, 2026

How to use

In the Butter plugin, enable the variant file metafield in the CMS field picker's Variants subsection and sync — this creates a CMS string field holding each variant's file CDN URL.
Place the component on the canvas.
Connect ⛁ Butter Data to the product's Butter Data CMS field.
Connect ⛁ Metafield to that metafield's CMS field.
Choose Display: Single and set ↳ Slot (1-based) for list file metafields, or All and configure ↳ Layout.
Open Style to set image Fit/Fill (default Fit), Padding, Radius, and an optional BG.
If the metafield holds video files, open Video to set Auto-play, Loop, Muted, Controls, and a Poster overlay (shown when Auto-play is off).
Set the component's height to Fit so it hugs the media.

There's no separate Alt Text control — alt text is read automatically from the file's Shopify alt text, synced into the CMS value.

What shows, and what happens when a variant has no file

Exactly one thing renders, chosen from the selected variant:

Variant selected and a file exists for it → renders that variant's image or video. Video vs. image is detected automatically from the file extension (.mp4, .webm, .mov, etc.).
Variant selected but no file for it, or no variant selected yet → renders nothing — a transparent, sized container that keeps the layout intact rather than collapsing.
On the Framer canvas: connected, it previews the first file in the connected field; unconnected, it shows a neutral image placeholder on the Style BG so you can size the layout.

Showing one file or every file from a list metafield

When the metafield holds a list of files, Display controls how many show:

Single shows one file, chosen by the 1-based ↳ Slot number.
All shows every file in the list, arranged with ↳ Layout — the same Img Width/Height and stack/grid/gap options as Media Variant Static. Each item gets the same Style and Video treatment.

Video playback: autoplay, controls, and poster images

For file metafields that hold video, the Video panel controls playback: Auto-play, Loop, and Muted, plus custom Controls chrome and a Poster overlay shown when Auto-play is off. Video uses this custom chrome rather than native browser controls. Auto-play is automatically suppressed when the customer's device is set to prefer reduced motion.

Not part of the product gallery — and other constraints to know

This is a standalone element for one variant's file — it doesn't join the product gallery, so there's no slideshow, counters, zoom, or thumbnail states. For the gallery itself, use the Media components.

Both ⛁ Butter Data and ⛁ Metafield must be connected — the file lives in the metafield's own CMS field, not in Butter Data.
Files load directly from Shopify's servers, not Framer's — they'll look exactly as uploaded, without Framer's image processing.
Changes to the file in Shopify appear after your next sync, not instantly.
If your store is connected without full admin access, only metafields marked publicly visible in Shopify will sync — the plugin tells you after the sync if some were skipped.