Skip to content
Tutorials Center
My learning

Topics

Lesson 54 of 61 ยท Projects

Project: A Configurable Hero Banner Section

Build a Shopify hero banner section with an image picker, text and button blocks, an overlay, responsive images, a color scheme setting and presets.

The hero banner is the first thing most visitors see, and it is the section merchants edit most often: a new photo for each campaign, a new headline for each sale. A good hero is therefore not a fixed piece of HTML. It is a small product with settings, blocks and sensible defaults, so that a merchant can change it in the theme editor without calling you.

In this project you build one from start to finish: the schema, the image picker, text and button blocks, a dark overlay for readable text, responsive images, a color scheme setting and a preset so the section appears in the "Add section" list with good default content. It uses ideas from Building a Section, Blocks and Theme Blocks, Schema Settings and Setting Types in Depth and Product Media: Images, Video and 3D.

The theme code below targets current Online Store 2.0 themes and is read-only: this site has no Liquid engine, so it cannot render it. The runnable examples are JavaScript stand-ins. One computes the image sizes the Liquid would ask for, and one is a live preview that mimics the section's settings. Setting names, markup and CSS here are our own design, not copied from any theme.

Plan the section

Write down what a merchant should control before you write code:

Control Kind Why
Background image Setting (image_picker) Changes with every campaign
Section height Setting (select) Small, medium or large
Overlay opacity Setting (range) Keeps text readable on any photo
Content alignment Setting (select) Left, center or right
Color scheme Setting (color_scheme) Text and button colors that match the theme
Heading, text, button Blocks Merchants can reorder, remove and repeat them

Settings describe the section as a whole. Blocks are the repeatable pieces inside it. Making the text parts blocks means a merchant can drop the paragraph, add a second button or put a small label above the heading, all without a developer.

flowchart TB
  S["Section: hero-banner"] --> I["image_picker setting"]
  S --> O["overlay + height + alignment settings"]
  S --> C["color_scheme setting"]
  S --> B["blocks"]
  B --> H["heading block"]
  B --> T["text block"]
  B --> U["button block"]

The section owns the picture and the layout. The blocks own the words.

Step 1: the markup

Create sections/hero-banner.liquid. The structure is one wrapper that holds the image, an overlay element, and the content:

LIQUID
{%- liquid
  assign image = section.settings.image
  assign overlay = section.settings.overlay_opacity | divided_by: 100.0
-%}

<section
  class="hero hero--{{ section.settings.height }} hero--{{ section.settings.alignment }} color-{{ section.settings.color_scheme }}"
  style="--hero-overlay: {{ overlay }};"
>
  {%- if image != blank -%}
    {{
      image
      | image_url: width: 2400
      | image_tag:
        widths: '600, 900, 1200, 1600, 2000, 2400',
        sizes: '100vw',
        class: 'hero__image',
        loading: 'eager',
        fetchpriority: 'high'
    }}
  {%- else -%}
    {{ 'hero-apparel-1' | placeholder_svg_tag: 'hero__image hero__placeholder' }}
  {%- endif -%}

  <div class="hero__overlay"></div>

  <div class="hero__content page-width">
    {%- for block in section.blocks -%}
      {%- case block.type -%}
        {%- when 'heading' -%}
          <h2 class="hero__heading" {{ block.shopify_attributes }}>
            {{ block.settings.heading | escape }}
          </h2>
        {%- when 'text' -%}
          <div class="hero__text rte" {{ block.shopify_attributes }}>
            {{ block.settings.text }}
          </div>
        {%- when 'button' -%}
          {%- if block.settings.label != blank -%}
            <a
              class="hero__button"
              href="{{ block.settings.link | default: routes.all_products_collection_url }}"
              {{ block.shopify_attributes }}
            >
              {{ block.settings.label | escape }}
            </a>
          {%- endif -%}
      {%- endcase -%}
    {%- endfor -%}
  </div>
</section>

Several details matter here.

  • image_url and image_tag. image_url: width: 2400 builds a URL for the largest size we want. image_tag then writes an <img> with a srcset made from the widths list, so the browser downloads only what the screen needs. sizes: '100vw' tells the browser the image fills the viewport width. Without sizes, the browser assumes a smaller slot and may pick a blurry file.
  • Eager loading. A hero is normally the largest thing on the screen at load time, so we do not lazy-load it. loading: 'eager' and fetchpriority: 'high' ask the browser to fetch it early. This helps the Largest Contentful Paint score; see Theme Performance and Core Web Vitals. If you place the hero lower on a page, switch to loading: 'lazy'.
  • Alt text. image_tag uses the alt text stored on the image in the admin. A decorative hero background can have empty alt text; if the image carries information, merchants should fill it in.
  • escape on text settings. text and inline_richtext settings can contain characters you should not trust as HTML. Single-line text goes through escape; richtext is already sanitized HTML by Shopify, so it is printed as is. See Security in Themes.
  • A fallback for no image. A brand-new section has no image. placeholder_svg_tag draws a placeholder so the section still looks intentional in the editor.
  • block.shopify_attributes. It lets the theme editor highlight a block when the merchant clicks it. It prints nothing on the live storefront.

Step 2: the schema

Add the {% schema %} tag at the bottom of the same file. It lists the settings, the block types and the preset:

LIQUID
{% schema %}
{
  "name": "Hero banner",
  "tag": "section",
  "class": "section-hero",
  "settings": [
    { "type": "image_picker", "id": "image", "label": "Background image" },
    {
      "type": "select",
      "id": "height",
      "label": "Section height",
      "options": [
        { "value": "small", "label": "Small" },
        { "value": "medium", "label": "Medium" },
        { "value": "large", "label": "Large" }
      ],
      "default": "medium"
    },
    {
      "type": "select",
      "id": "alignment",
      "label": "Content alignment",
      "options": [
        { "value": "left", "label": "Left" },
        { "value": "center", "label": "Center" },
        { "value": "right", "label": "Right" }
      ],
      "default": "left"
    },
    {
      "type": "range",
      "id": "overlay_opacity",
      "label": "Overlay opacity",
      "min": 0,
      "max": 80,
      "step": 5,
      "unit": "%",
      "default": 30
    },
    {
      "type": "color_scheme",
      "id": "color_scheme",
      "label": "Color scheme",
      "default": "scheme-1"
    }
  ],
  "blocks": [
    {
      "type": "heading",
      "name": "Heading",
      "limit": 1,
      "settings": [
        { "type": "text", "id": "heading", "label": "Heading", "default": "Spring collection" }
      ]
    },
    {
      "type": "text",
      "name": "Text",
      "limit": 1,
      "settings": [
        { "type": "richtext", "id": "text", "label": "Text", "default": "<p>Fresh colors for longer days.</p>" }
      ]
    },
    {
      "type": "button",
      "name": "Button",
      "limit": 2,
      "settings": [
        { "type": "text", "id": "label", "label": "Label", "default": "Shop now" },
        { "type": "url", "id": "link", "label": "Link" }
      ]
    }
  ],
  "presets": [
    {
      "name": "Hero banner",
      "blocks": [
        { "type": "heading" },
        { "type": "text" },
        { "type": "button" }
      ]
    }
  ]
}
{% endschema %}

Check each part against the rules from Schema Settings and Setting Types in Depth:

  • A range needs min, max, step and a default that lands on a step. Here the steps are 0, 5, 10 ... 80, and the default is 30. A range is limited in how many steps it may have, so keep the step size reasonable.
  • A select default must match one of the option values.
  • A color_scheme setting reads the schemes defined in config/settings_schema.json (see Global Theme Settings: settings_schema.json and settings_data.json). The default must name a scheme that exists, or the editor shows an error.
  • limit on blocks stops merchants from adding five headings. Buttons are allowed twice, for a primary and secondary action.
  • The preset is what makes the section appear in the editor's "Add section" menu. Without presets, the section can only be used by a developer in a JSON template. The preset lists the blocks that are created when the section is added, which gives the merchant a working banner at once.

Step 3: the CSS

Put the styles in assets/hero-banner.css or in a {% stylesheet %} tag inside the section. The key idea is that the image fills the wrapper, the overlay sits above it, and the content sits above both:

CSS
.hero {
  position: relative;
  display: grid;
  align-items: center;
  overflow: hidden;
  background: rgb(var(--color-background));
  color: rgb(var(--color-foreground));
}
.hero--small { min-height: 20rem; }
.hero--medium { min-height: 32rem; }
.hero--large { min-height: 48rem; }

.hero__image {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  object-fit: cover;
}
.hero__overlay {
  position: absolute;
  inset: 0;
  background: #000;
  opacity: var(--hero-overlay);
}
.hero__content {
  position: relative;
  display: grid;
  gap: 1rem;
  justify-items: start;
  max-width: 60rem;
}
.hero--center .hero__content { justify-items: center; text-align: center; margin-inline: auto; }
.hero--right .hero__content { justify-items: end; text-align: right; margin-inline-start: auto; }

The variable names --color-background and --color-foreground come from the color scheme mechanism of the theme you use; yours may differ. object-fit: cover crops the photo to fill the box on any screen size. For more CSS patterns, see CSS for Themes: Variables, Layout and Responsiveness.

Text on top of an image is a contrast risk. The overlay raises the contrast, but you must still check it: white text on a 30% black overlay over a bright sky may fail. Give merchants a higher maximum overlay and tell them in the setting's info text. See Accessibility in Themes.

Step 4: the stand-in for responsive images

You cannot run image_tag here, but the idea behind it is easy to model. Given a list of widths, it produces a srcset with one entry per width, never larger than the original image. This stand-in builds the string and shows which file a browser would choose for different screens. It assumes a device pixel ratio of 1 and 2, and the sizes value 100vw.

JS Stand-in: build a srcset and pick a file

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Browsers decide for themselves, so a real browser may pick a different entry (it also considers network conditions and cache). The model shows the rule of thumb: the smallest file that is still wide enough.

Step 5: a live preview stand-in

The editor's value is that changes appear instantly. This stand-in mimics that: it keeps the section's settings in an object, renders a banner from them, and lets you change the settings with the controls. It is plain HTML, CSS and JavaScript, using one of our own sample images. In a real store, Shopify's editor re-renders the section on the server, using the Liquid above.

Stand-in: a hero banner you can configure

Notice the heading is passed through escapeHtml. That is the JavaScript version of Liquid's escape filter: type <b>hi</b> in the heading box and it is shown as text, not as markup.

Step 6: use it on a page

A section with a preset is ready for the editor, but you can also place it in a JSON template yourself, for example at the top of templates/index.json:

JSON
{
  "sections": {
    "hero": {
      "type": "hero-banner",
      "blocks": {
        "title": { "type": "heading", "settings": { "heading": "Spring collection" } },
        "cta": { "type": "button", "settings": { "label": "Shop now" } }
      },
      "block_order": ["title", "cta"],
      "settings": { "height": "large", "overlay_opacity": 35 }
    }
  },
  "order": ["hero"]
}

Settings you leave out use the schema defaults. Test the section in the editor by adding it, uploading a bright photo and a dark photo, changing the overlay, deleting each block and adding a second button. Also check it on a narrow screen. Run Theme Check on the file (see Theme Check, Linting and Testing) and then follow Testing, Publishing and Going Live before it reaches a live store.

Ideas to extend it

  • Add a video setting that plays a muted background video, with the image as the poster.
  • Add a mobile-specific image with a second image_picker and a <picture> element.
  • Add a visible_if condition, for example showing the overlay setting only when an image is chosen.
  • Move the three block types into theme blocks so other sections can reuse them.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the hero use loading: 'eager' and fetchpriority: 'high' on its image?

    A hero image is usually the Largest Contentful Paint element. Loading it eagerly with high priority helps that metric. Images lower on the page should still be lazy-loaded.
  2. 2. What makes the section appear in the editor's Add section list?

    Sections without presets can only be added by a developer in a JSON template. A preset registers the section in the Add section menu and defines its starting blocks.
  3. 3. Why are the heading, text and button blocks instead of settings?

    Settings describe the section as a whole. Blocks are repeatable pieces, so the merchant controls which text parts appear and in what order.
  4. 4. What does the overlay solve?

    A semi-transparent dark layer between the image and the text makes text readable over bright photos. You should still check the contrast ratio.
  5. 5. Why is the single-line heading printed with the escape filter?

    Merchant-entered text is data, not trusted markup. escape turns characters such as < and & into HTML entities.

Summary

  • A hero banner is a section with settings for the whole (image, height, alignment, overlay, color scheme) and blocks for the words (heading, text, button).
  • image_url plus image_tag with widths and sizes gives responsive images; the hero is loaded eagerly with high fetch priority.
  • Escape single-line text, and give every empty state (no image, no button label, no link) a fallback.
  • block.shopify_attributes lets the editor select blocks; limit keeps blocks under control.
  • The schema needs valid defaults, and a preset puts the section in the Add section menu with working starter blocks.
  • Use an overlay for readability, but still check contrast, and test with bright and dark photos.

Next, build a reusable card in Project: A Product Card Snippet with Quick Add.