Media v2

Media v2 fields offer the upload of multiple media in a single field, which can be arranged in order and more easily managed in the editor. Each media also offers properties for easy access to structured information about media type, image dimensions, aspect ratio, ALT text, etc.

This is the recommended way to create fields for uploading images, videos or other types of media.

Media v2 fields support a variety of file types such as:

  • JPG/JPEG, PNG, ICO, TIF, WEBP, GIF and SVG images

  • PDF, CSV, TXT, ZIP and JSON files

  • AI, PS and EPS (Postscript) files

  • MP3, MP4, WEBM and MOV (Quicktime) files

  • GLB files (3D images used in Shopify)

  • Font files (WOFF, WOFF2, TTF and OTF)

When defining fields, you determine the set of allowed filetypes to be uploaded via the editor.

If you need a media type not currently available, get in touch and we'll add it for you.

Uploaded media are automatically stored in our highly secure cloud bucket (with full redundancy and daily backup). The corresponding link to the file is stored in the Metafield, ready to use in Liquid. Part of the field definition is whether or not the field supports the upload of multiple media to the same field. If multiple media are allowed, you can upload more than one media in the same field.

Media properties

The media information is stored as JSON objects with the following properties:


For internal ACF use only. This uniquely identifies the individual media.


For internal ACF use only. This is the scope for which the media is uploaded (e.g. a product id when uploaded for a product)


For internal ACF use only. This is the uploaded media's filename appended to a combination of the scope and the media's id (e.g. which field in which product;


The URL points to the uploaded media. Use this as the value for referring to the media source over HTTPS e.g. in the "src" attribute in image tags etc. You can optionally append transformation options to this URL for resizing and cropping - please see Resize & crop images


This is basically the same as src, but the domain is here rather than, which provides access to your original (and unoptimized, see below) media. This should normally not be used for other purposes than redownloading the original media, since performance will not be as good as its src counterpart.


A special URL for ease of use of our previous integration with Cloudinary for resizing, cropping, etc. of images. This property will continue to be available and in working condition but we do offer new resizing options - see the .src property above.


The name of the media, when it was uploaded to ACF (including the extension, but excluding any folders)


The media's handle is a string version of the media's id. This is used when doing lookups using a Media Reference field


The mime type of the uploaded media, identifying exactly which type of media is contained in the file. Example: "image/jpg", "video/mp4" etc.


Contains the general type of the media such as "image", "video", "audio", "pdf" etc.


Contains the actual file content of an uploaded SVG file, if the option to store it inline was enabled at the time of upload.


For media of media_type "image", an ALT text can be provided in the ACF editor and is made available via this property.


The width of the image in pixels.


The height of the image in pixels.


The aspect ratio ( width / height ) of the image, which tells the orientation of the image:

  • less than 1.0 is a portrait image

  • exactly 1.0 is a square image

  • greater than 1.0 is a landscape image


The underlying Metafield value will always be an iterable array. If just a single media is uploaded, the array will only have one entry. This allows for consistent use of Liquid's array filters such as first, last, sort, where, etc no matter how many media are uploaded.

If you define a Media v2 field as repeatable, you will essentially get an array of arrays in the underlying Metafield value

Basic list of all uploaded images:

{% for image in product.metafields.accentuate.multi_images %}
  <img src="{{ image.src }}" alt="{{ image.alt }}"/>
{% endfor %}

Basic list of all uploaded images in a repeatable media v2 field:

{% for multi_images in product.metafields.accentuate.repeatable_multi_images %} 
  {% for image in multi_images %} 
    <img src="{{ image.src }}" alt="{{ image.alt }}"/>
  {% endfor %}
{% endfor %}

Resizing the first image to 200 pixels wide, keeping the aspect ratio:

{% assign img = product.metafields.accentuate.multi_images | first %} 
<img src="{{ img.src | append: '&transform=resize=200' }}" alt="{{ img.alt }}"/>

Filtering uploaded medias by media type:

{% assign doc_files = product.metafields.accentuate.doc_files | where: 'media_type', 'pdf' %}
{% for pdf in doc_files %} 
    <a href="{{ pdf.src }}">{{ pdf.filename }}</a> 
{% endfor %}

Note: Media are served directly via world-class software services with very low network latency. ACF also employs performance optimization techniques similar to Shopify when fetching images via, including transforming images to WEBP format for supporting browsers. While the performance of ACF's media delivery has been optimized for a balance of speed and quality, you should still consider further optimizations. ACF currently has a limit of ~50MB per single media upload. You will typically only reach this limit when uploading video files. Take care not to force your visitors to download assets of this size but consider using a streaming service for large video files (like YouTube, Vimeo, etc.)

Last updated