Skip to content
Shopify Theme Handbook

Assets Management

TL;DR: Everything media in one place — icons, responsive images, video, and 3D/AR product media, with maintainability and performance as the throughline.

This section covers every kind of media asset in this theme: icons, product and static images, video, and 3D/AR models. Each media type gets its own dedicated page, and one shared page ties together the rules that apply no matter which type you’re working with. Facts throughout this section are verified directly against Shopify’s own Liquid filter references and best-practices documentation, not just general web knowledge.

Quick answers

Section titled “Quick answers”

“How do I add an icon?” See Icon Management. An inline SVG snippet, named icon-*, using currentColor for theming.

“My image looks blurry / loads a huge file for a small thumbnail.” See Responsive Images. You’re probably requesting a width far larger than the image actually renders at.

“Do I need to write loading: 'lazy' on every image and video?” No — see Responsive Images: lazy loading. image_tag and video_tag already default to lazy for below-the-fold media. You only need to be explicit for your above-the-fold LCP candidate.

“Why does my uploaded video look choppy on slow connections?” See Video Management. Make sure you’re using video_tag, not a hand-written <video> tag — video_tag includes the adaptive HLS source Shopify generates automatically.

“Should a 3D model load right away on the product page?” No, by default — see 3D & AR Media. Use reveal: 'interaction' so the heavy model file only loads once a customer engages with it.

“What’s the one thing that applies to every media type?” See Asset Organization & Performance: reserve its space. Reserve every media element’s space with explicit dimensions or aspect-ratio before it loads, or you’ll pay a layout-shift penalty.

What’s in this section

Section titled “What’s in this section”
PageCovers
Icon ManagementInline SVG snippets, currentColor theming, sizing, accessibility, settings-driven icon pickers, keeping the icon set maintainable
Responsive Imagesimage_url/image_tag in full: sizing, cropping, format selection, srcset/sizes, focal points, lazy loading, alt text
Video Managementvideo_tag/external_video_tag, adaptive HLS, autoplay rules, poster images, responsive containers
3D & AR Mediamodel_viewer_tag, gating a model’s load cost, AR Quick Look/Scene Viewer via the shopify-xr library
Asset Organization & PerformanceThe shared rules: reserving space, CDN hosting, preloading deliberately, naming conventions, and auditing for bloat over time

The throughline: maintainability and performance, not just “how do I render this”

Section titled “The throughline: maintainability and performance, not just “how do I render this””

Every page in this section could stop at “here’s the Liquid filter that renders this media type.” Instead, each one goes one step further: how to keep the cost of that media type under control (request sizes, lazy loading, gating heavy 3D loads), and how to keep the codebase around it maintainable as the theme grows (consistent naming, pruning unused icons and orphaned assets, re-checking loading defaults after a redesign). A theme that renders media correctly on day one but never revisits it tends to accumulate real bloat by year two.

Best practices

Section titled “Best practices”
  • Start with Asset Organization & Performance if you want the shared rules before diving into one specific media type.
  • Always reach for Shopify’s own filters (image_tag, video_tag, model_viewer_tag) instead of hand-writing markup. They handle responsive sizing, format selection, and adaptive streaming correctly by default.
  • Treat “reserve the media’s space before it loads” as a non-negotiable rule, not a nice-to-have, for every single media element you ship.

Further reading

Section titled “Further reading”