Media Blocks

Auto-generate your docs

Overview

Media blocks handle visual content including images and videos. Horizon provides three media block types:

Image Block - Static images with aspect ratio controls
Video Block - Uploaded or external videos with playback options
Media Block - Unified block supporting both images and videos

Image Block

Displays responsive images with aspect ratio control and optional linking.

Settings

image_picker

Image to display

url

Optional URL to link the image

Size Settings

select

default:"adapt"

Image aspect ratio

adapt - Use original image ratio
portrait - 4:5 ratio (taller)
square - 1:1 ratio
landscape - 16:9 ratio (wider)

select

default:"fill"

Desktop width behavior

fit-content - Fit to image size
fill - Fill available space
custom - Custom percentage

range

default:"100"

Custom width percentage (0-100%, visible when width is “custom”)

select

default:"fill"

Mobile width behavior

fit-content - Fit to image
fill - Fill container
custom - Custom percentage

range

default:"100"

Mobile custom width (0-100%)

select

default:"fit"

Height behavior (visible when image_ratio is “adapt”)

fit - Fit to content
fill - Fill container height

Border Settings

select

default:"none"

Border style (none or solid)

range

default:"1"

Border thickness (0-100px)

range

default:"100"

Border opacity (0-100%)

range

default:"0"

Corner radius (0-100px)

Padding Settings

Standard padding controls (0-100px) for all four sides.

Liquid Implementation

{% liquid
  assign block_settings = block.settings
  assign ratio = 1

  case block_settings.image_ratio
    when 'landscape'
      assign ratio = '16 / 9'
    when 'portrait'
      assign ratio = '4 / 5'
    when 'adapt'
      assign ratio = block_settings.image.aspect_ratio
  endcase

  if ratio == 0 or ratio == null
    assign ratio = 1
  endif
%}

{% capture image %}
  {%- if block_settings.image -%}
    {{
      block_settings.image
      | image_url: width: 3840
      | image_tag:
        widths: '240, 352, 832, 1200, 1600, 1920, 2560, 3840',
        sizes: 'auto',
        class: 'image-block__image border-style'
    }}
  {%- else -%}
    <div class="placeholder-image">
      {{ 'detailed-apparel-1' | placeholder_svg_tag }}
    </div>
  {%- endif -%}
{% endcapture %}

{% if block_settings.link == blank %}
  <div class="image-block" style="--ratio: {{ ratio }};" {{ block.shopify_attributes }}>
    {{ image }}
  </div>
{% else %}
  <a href="{{ block_settings.link }}" class="image-block">
    {{ image }}
  </a>
{% endif %}

CSS Classes

.image-block - Main container with flex display
.image-block__image - Image element with object-fit cover
.image-block--height-fill - Fills parent height
.placeholder-image - Placeholder when no image selected
.border-style - Border styling utilities

Video Block

Supports both uploaded videos and external video URLs (YouTube, Vimeo).

Settings

select

default:"uploaded"

Video source type

uploaded - Shopify-hosted video file
url - External video URL

video

Uploaded video file (visible when source is “uploaded”)

video_url

External video URL from YouTube or Vimeo (visible when source is “url”)

checkbox

default:"false"

Autoplay video on page load

checkbox

default:"true"

Loop video playback

image_picker

Custom cover/poster image (visible for external videos when autoplay is off)

text

Alternative text for accessibility (visible for external videos)

Size Settings

range

default:"100"

Desktop width (0-100%)

range

default:"100"

Mobile width (0-100%)

select

default:"auto"

Video aspect ratio (for external videos without cover image)

auto - Automatic
9/16 - Portrait (9:16)
1/1 - Square
16/9 - Landscape (16:9)

Liquid Implementation

{% assign block_settings = block.settings %}

{% if block_settings.source == 'uploaded' %}
  {% render 'video',
    video: block_settings.video,
    video_loop: block_settings.video_loop,
    video_preview_image: block_settings.video.preview_image,
    section_id: section.id
  %}
{% else %}
  {% render 'video',
    video_from_url: true,
    video: block_settings.video_url.id,
    video_type: block_settings.video_url.type,
    video_alt: block_settings.alt,
    video_preview_image: block_settings.cover_image,
    section_id: section.id
  %}
{% endif %}

Media Block

Unified block that can display either an image or video based on settings.

Settings

select

default:"image"

Type of media to display

image - Static image
video - Video content

image_picker

Image to display (visible when media_type is “image”)

url

Link URL (visible when media_type is “image”)

video

Video file (visible when media_type is “video”)

checkbox

default:"true"

Loop video playback (visible when media_type is “video”)

checkbox

default:"false"

Autoplay video (visible when media_type is “video”)

Appearance Settings

checkbox

default:"true"

Inherit color scheme from parent section

color_scheme

default:"scheme-1"

Color scheme when not inheriting

range

default:"0"

Corner radius (0-100px)

Padding Settings

Standard padding controls for all four sides (0-100px).

Liquid Implementation

{% render 'media', section_id: section.id %}

The media block uses the media snippet which handles the conditional rendering of images or videos.

Responsive Images

All image blocks use Shopify’s responsive image system:

{{
  image
  | image_url: width: 3840
  | image_tag:
    widths: '240, 352, 832, 1200, 1600, 1920, 2560, 3840',
    sizes: 'auto'
}}

This generates:

Multiple image sizes in srcset
Automatic size selection based on viewport
Lazy loading support
Optimal performance

Usage Examples

Hero Image

{
  "type": "image",
  "settings": {
    "image": "hero.jpg",
    "image_ratio": "landscape",
    "width": "fill",
    "link": "/collections/new"
  }
}

Looping Background Video

{
  "type": "video",
  "settings": {
    "source": "uploaded",
    "video_autoplay": true,
    "video_loop": true,
    "custom_width": 100
  }
}

YouTube Embed

{
  "type": "video",
  "settings": {
    "source": "url",
    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "cover_image": "video-poster.jpg",
    "aspect_ratio": "16/9"
  }
}

Gallery Layout

{
  "blocks": [
    {
      "type": "image",
      "settings": {
        "image_ratio": "square",
        "width": "custom",
        "custom_width": 50,
        "border_radius": 8
      }
    },
    {
      "type": "image",
      "settings": {
        "image_ratio": "square",
        "width": "custom",
        "custom_width": 50,
        "border_radius": 8
      }
    }
  ]
}

Best Practices

Image Optimization

Upload high-resolution images (at least 2000px wide)
Use appropriate formats (WebP for photos, SVG for logos)
Set alt text for accessibility
Choose correct aspect ratio to avoid cropping

Video Performance

Use autoplay sparingly - Can impact page performance
Provide cover images - Faster initial load
Consider file size - Compress videos before upload
Use external URLs - YouTube/Vimeo for longer content

Responsive Design

Set mobile widths - Different sizing for small screens
Test aspect ratios - Ensure content looks good at all sizes
Use adaptive ratios - When image proportions are important
Add padding - Provide breathing room on mobile

Source Code Reference

Image Block: /source/blocks/image.liquid:1-331
Video Block: /source/blocks/video.liquid:1-255
Media Block: /source/blocks/_media.liquid:1-135

⌘I

Sections

Blocks

Snippets

Web Components

Overview

Image Block

Settings

Size Settings

Border Settings

Padding Settings

Liquid Implementation

CSS Classes

Video Block

Settings

Size Settings

Liquid Implementation

Media Block

Settings

Appearance Settings

Padding Settings

Liquid Implementation

Responsive Images

Usage Examples

Hero Image

Looping Background Video

YouTube Embed

Gallery Layout

Best Practices

Image Optimization

Video Performance

Responsive Design

Source Code Reference

​Overview

​Image Block

​Settings

​Size Settings

​Border Settings

​Padding Settings

​Liquid Implementation

​CSS Classes

​Video Block

​Settings

​Size Settings

​Liquid Implementation

​Media Block

​Settings

​Appearance Settings

​Padding Settings

​Liquid Implementation

​Responsive Images

​Usage Examples

​Hero Image

​Looping Background Video

​YouTube Embed

​Gallery Layout

​Best Practices

​Image Optimization

​Video Performance

​Responsive Design

​Source Code Reference

Overview

Image Block

Settings

Size Settings

Border Settings

Padding Settings

Liquid Implementation

CSS Classes

Video Block

Settings

Size Settings

Liquid Implementation

Media Block

Settings

Appearance Settings

Padding Settings

Liquid Implementation

Responsive Images

Usage Examples

Hero Image

Looping Background Video

YouTube Embed

Gallery Layout

Best Practices

Image Optimization

Video Performance

Responsive Design

Source Code Reference