Skip to main content
The Hero section creates impactful banner areas with support for dual media (side-by-side images/videos), custom mobile media, and flexible content positioning.

​
Schema Location

File: sections/hero.liquid:747-1497

​
Features

  • Dual media slots (2 images or videos side-by-side)
  • Separate desktop and mobile media
  • Blurred reflection effect
  • Flexible content layout (vertical or horizontal)
  • Multiple height options including full-screen
  • Custom overlay gradients
  • Support for all theme blocks (@theme, text, button, logo, etc.)

​
Settings

​
Media Configuration

​
media_type_1
select
default:"image"
Type of media for slot 1Options:
  • image - Static image
  • video - Video file
​
image_1
image_picker
Image for media slot 1Visible when: media_type_1 == 'image'
​
video_1
video
Video for media slot 1 (autoplay, loop, muted)Visible when: media_type_1 == 'video'
​
media_type_2
select
default:"image"
Type of media for slot 2Options:
  • image - Static image
  • video - Video file
​
image_2
image_picker
Image for media slot 2
​
video_2
video
Video for media slot 2

​
Mobile Media

​
custom_mobile_media
checkbox
default:"false"
Enable custom media for mobile devices
​
stack_media_on_mobile
checkbox
default:"false"
Stack media vertically on mobile instead of side-by-side
​
media_type_1_mobile
select
default:"image"
Media type for mobile slot 1Visible when: custom_mobile_media is enabled
​
image_1_mobile
image_picker
Mobile image for slot 1
​
video_1_mobile
video
Mobile video for slot 1

​
Section Link

​
link
url
Make the entire section clickable
​
open_in_new_tab
checkbox
default:"false"
Open link in new tab

​
Layout

​
content_direction
select
default:"column"
Content arrangement directionOptions:
  • column - Vertical stacking
  • row - Horizontal alignment
​
vertical_on_mobile
checkbox
default:"true"
Force vertical layout on mobileVisible when: content_direction == 'row'
​
horizontal_alignment
select
default:"flex-start"
Horizontal alignment for row layoutOptions:
  • flex-start - Left
  • center - Center
  • flex-end - Right
  • space-between - Space between
​
vertical_alignment
select
default:"center"
Vertical position for row layoutOptions:
  • flex-start - Top
  • center - Center
  • flex-end - Bottom
​
vertical_alignment_flex_direction_column
select
default:"center"
Vertical position for column layoutOptions:
  • flex-start - Top
  • center - Center
  • flex-end - Bottom
  • space-between - Space between
​
gap
range
default:"12"
Spacing between blocksRange: 0-100px, step 1
​
section_width
select
default:"page-width"
Content area widthOptions:
  • page-width - Constrained to page width
  • full-width - Full viewport width
​
section_height
select
default:"medium"
Section minimum heightOptions:
  • auto - Fit content
  • small - Small height
  • medium - Medium height
  • large - Large height
  • full-screen - 100vh
  • custom - Custom percentage
​
section_height_custom
range
default:"50"
Custom height percentageRange: 0-100%, step 1
Visible when: section_height == 'custom'

​
Appearance

​
color_scheme
color_scheme
default:"scheme-1"
Color scheme for text and content
​
toggle_overlay
checkbox
default:"false"
Enable media overlay
​
overlay_color
color
default:"#00000026"
Overlay color with alpha supportVisible when: toggle_overlay is enabled
​
overlay_style
select
default:"solid"
Overlay appearanceOptions:
  • solid - Solid color overlay
  • gradient - Gradient overlay
​
gradient_direction
select
default:"to top"
Gradient directionOptions:
  • to top - Bottom to top
  • to bottom - Top to bottom
​
blurred_reflection
checkbox
default:"false"
Add blurred reflection effect below section (images only)
​
reflection_opacity
range
default:"75"
Reflection opacity percentageRange: 0-100%, step 1

​
Padding

​
padding-block-start
range
default:"0"
Top padding in pixelsRange: 0-100px, step 1
​
padding-block-end
range
default:"0"
Bottom padding in pixelsRange: 0-100px, step 1

​
Supported Blocks

The Hero section accepts these block types:
  • @theme - All theme blocks
  • text - Text content
  • button - CTA buttons
  • logo - Logo images
  • jumbo-text - Large text
  • spacer - Spacing control
  • group - Block containers
  • _marquee - Scrolling text

​
Implementation Examples

​
Basic Hero with Centered Content

{% raw %}
{% content_for 'blocks' %}
  <div class="hero__content">
    <h1>New Arrivals</h1>
    <p>Made with care</p>
    <a href="/collections/all" class="button">Shop Now</a>
  </div>
{% endcontent_for %}
{% endraw %}

​
Dual Media Hero

{% raw %}
{% comment %}
  Hero section at sections/hero.liquid:16-31
  Checks both media slots for images or videos
{% endcomment %}

{% if section.settings.image_1 != blank and section.settings.media_type_1 == 'image' %}
  {% assign media_1 = 'image' %}
{% endif %}

{% if section.settings.image_2 != blank and section.settings.media_type_2 == 'image' %}
  {% assign media_2 = 'image' %}
{% endif %}
{% endraw %}

​
Mobile-Specific Media

{% raw %}
{% comment %}
  Custom mobile media handling at sections/hero.liquid:33-52
{% endcomment %}

{% if section.settings.custom_mobile_media %}
  {% if section.settings.image_1_mobile != blank and section.settings.media_type_1_mobile == 'image' %}
    {% assign media_1_mobile = 'image' %}
  {% endif %}
{% endif %}
{% endraw %}

​
CSS Custom Properties

The Hero section uses these CSS variables: 
--hero-border-style: {{ section.settings.border }};
--hero-border-width: {{ section.settings.border_width }}px;
--hero-border-opacity: {{ section.settings.border_opacity }}%;
--blur-opacity: {{ section.settings.reflection_opacity | divided_by: 100.0 }};
--hero-min-height: var(--section-height-{{ section.settings.section_height }});
--hero-media-count: {{ media_count }};
--hero-media-count-mobile: {{ media_count_mobile }};
--hero-media-aspect-ratio: {{ section.settings.image_1.aspect_ratio }};

​
Presets

The Hero section includes 3 presets:

​
1. Default Hero

Centered content with gradient overlay Settings:
  • Height: Large
  • Color scheme: scheme-5
  • Overlay: Gradient
  • Centered alignment

​
2. Hero with Marquee

Bottom-aligned content with scrolling text Settings:
  • Height: Large
  • Includes spacer and marquee blocks
  • Space-between vertical alignment

​
3. Bottom Aligned Hero

Complex grouped content at bottom with baseline alignment Settings:
  • Uses nested group blocks
  • Baseline alignment enabled
  • Content direction: row

​
Performance Optimization

The Hero section implements smart image loading:
{% raw %}
{% assign fetch_priority = 'auto' %}
{% if section.index == 1 %}
  {% assign fetch_priority = 'high' %}
{% endif %}
{% endraw %}
First hero section gets fetchpriority="high" for LCP optimization.
Desktop widths: 832, 1200, 1600, 1920, 2560, 3840Mobile widths: 416, 600, 800, 1200, 1600
{% raw %}
{{ section.settings.image_1
  | image_url: width: 3840
  | image_tag: widths: '832, 1200, 1600, 1920, 2560, 3840',
              sizes: sizes,
              fetchpriority: fetch_priority
}}
{% endraw %}

​
Accessibility

  • Provide descriptive alt text for all images
  • Ensure text has sufficient contrast against background media
  • Use overlay when text readability is compromised
  • Test keyboard navigation for clickable sections

​
Related Sections

Slideshow

Multi-slide banner rotation

Layered Slideshow

Advanced multi-layer animations

Media with Content

Image/video with text pairing

Build docs developers (and LLMs) love

Get started for freeTalk to us