Media v2 fields

Media v2 fields offer upload of multiple medias 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 and other types of media

Media fields currently supports the following media types

  • 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 in the list, get in touch and we'll add it for you

Uploaded medias 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 upload of multiple medias to the same field. If multiple medias are allowed, you can upload more than one media in the same field.

Important: Shopify currently has a 100,000 bytes limit for metafields. Since ACF stores the array of media objects (see below "Media properties") in a single metafield, this limits how many medias you can store in a single field. 100,000 bytes translates to ~150 media objects

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)

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 pointing the to uploaded media.

Use this as the value for referring to the media source over HTTP e.g. in the "src" attribute in image tags etc. The value of src is constructed to ensure that any new or replaced media file, even with the same filename, will reach your visitors' browsers straight away.


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 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 Cloudinary integration for resizing, cropping etc. of images only. See related articles below as well as the examples on this page.


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 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 medias 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


Important: 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.

Also: if you define a Media v2 field as repeatable, your 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 via Cloudinary to 200 by 200 pixels, keeping the aspect ratio

{% assign img = product.metafields.accentuate.multi_images | first %} 
<img src="{{ img.cloudinary_src | append: 'w_200,h_200' }}" alt="{{ img.alt }}"/>

Filtering uploaded medias by media type:

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

Note: Medias 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  (WEBP is only served if the resulting image is in fact smaller than the original image after optimisation)

While performance of ACF's media delivery has been optimized for a balance of speed and quality, nothing beats not downloading images not needed at all. You should still consider only loading images when needed, aka "lazyloading". Google explains the concept here and you can find a popular 3rd-party library here

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us