Four Selectable How-To Step Layouts From a Single Metaobject Step List

One list of how_to_use step metaobjects renders as a card grid, a slider, a numbered timeline or an image-and-text split, chosen per product, with a desktop and a mobile asset per step and video that plays only while in view.

A Shopify metaobject list is data with no presentation, and one shape of step never fits a whole range. We render the how_to_use step list four ways — card grid, slider, numbered timeline, image-and-text split — from one capture that prints into both the desktop tab and the mobile accordion, with separate desktop and mobile assets per step and step video that plays only while it is on screen.

The Problem

A metaobject list in Shopify is a list of records: fields and order, and no opinion about how it should look. That's right for data and wrong for application instructions, because instructions differ across a range. A three-step wash routine wants numbered cards. A styling technique wants one full-bleed photo per step and a long caption beside it. A product with six steps wants a slider, not a grid that runs off the page.

Two more things about the same content. The photo that carries a step on desktop is usually the wrong crop on a phone, and a caption written for a wide card is too long for a narrow one. Where a step is a short video, autoplaying every one at once on mobile burns bandwidth on clips nobody is looking at. The content team wanted to write steps once and choose the presentation per product.

The Constraint

Metaobject fields don't arrive as one Liquid type. A field defined as a file reference, a Shopify-hosted video or a URL string each resolves differently, so every step field has to be unwrapped with .value | default: before it's safe to test — the same snippet has to accept both the raw drop and its unwrapped value.

Mobile autoplay is only permitted for muted, playsinline video. That rules out leaning on video_tag defaults: the element has to be built by hand with the attributes in place, and something on the client has to own when it loads and when it plays.

The steps also live inside the product information tabs, which render every panel twice — a desktop tablist and a mobile <details> accordion — and re-fetch themselves on variant change. Every layout therefore has to survive being printed into two trees and re-initialized after the tabs swap their How To content.

What We Built

product-info-tabs.liquid receives the step list and a layout choice — design_1 through design_4, a section select that a custom.how_to_design value on the variant or product can override. It builds the chosen layout once inside a {% capture %} named pit_capture_howto, then prints that capture into the desktop How To panel and again into the mobile accordion item, each container carrying data-howto-design so the variant refresh can swap the layout class with the content.

Four renderers. product-info-tabs-howto-grid-card.liquid is the first design: one <article> per step, media above title and copy. The tabs snippet lays those cards out as a grid, or — past four steps — as a desktop-only drag slider whose dots are generated in JavaScript from the cards per view (four from 990px, three below). The second design is the slider the tabs snippet builds itself: a track of slides, each with a desktop media layer and a title-and-copy overlay, plus a separate mobile block that reads img_style_2_mobile, video_mobile and text_style_2_mobile and falls back to the desktop asset and copy when they're empty. The phone doesn't get a rescaled desktop card; it gets a different asset and a shorter caption. product-info-tabs-howto-design3.liquid is an ordered list: each step carries a two-digit badge, an aria-hidden watermark numeral and a rail element the stylesheet turns into a vertical connector on mobile. product-info-tabs-howto-design4-split.liquid renders each step as an image column beside a scrollable text column, with per-step description_bg_color_style_4, description_bg_image_style_4 and description_text_color_style_4 composed into an inline style and a --d4s-text-color custom property, falling back to three section settings when the step leaves them blank. Past one step the split becomes a slider with dots.

Media per step. A use_img_or_video field decides whether a step shows its YouTube link, its hosted video or its image. YouTube URLs in four shapes — watch, youtu.be, embed, shorts — reduce to an id, embedded as a muted autoplaying loop with enablejsapi on so the theme can pause it. product-info-tabs-media-video.liquid emits a muted, playsinline, looping <video preload="none" disablepictureinpicture> with one <source data-src> per encoding and a poster from preview_image; a plain file reference goes through file_url with a video/mp4 default.

The client. A step video's sources attach from data-src only when its slide becomes active. On mobile, an IntersectionObserver per slide pauses anything below a quarter visible, a requestAnimationFrame-throttled scroll handler and a matchMedia('(max-width: 749px)') listener re-check what's on screen, and the per-slide scroll autoplay declines to bind under prefers-reduced-motion. It re-checks when the accordion opens and re-initializes when the tabs dispatch if-pit-howto-updated on variant change. A text_content_only field lets any step render as a plain rich-text row with no media chrome.

Why This Way

Four presentations behind one step schema means the content team writes a step once and the design is a setting, not a re-authoring job. The client's own record puts the layout decision with the product rather than in the theme editor, and scopes the How To to appear only where a product has steps — which is why the layout override rides on a product metafield and an empty list renders no panel.

There's a bill for the hand-built video path. Because the element is authored by hand, the theme owns everything video_tag would have handled: source attachment, the autoplay attributes, when to call play(), when to pause. That's a few hundred lines that have to run in two trees and again after every variant refresh.

The other cost lands on the person authoring a step. The mobile treatment works by having a second asset and a second caption to reach for, so a step can carry up to two images, two videos, a YouTube link and two bodies of copy. Nothing forces a merchandiser to fill the mobile fields — the fallbacks cover them — but the good version of a step takes more authoring than the default.

Implementation Notes

• The grid promotes itself to a slider when steps.size > 4; the slider and timeline designs are excluded from that promotion because each already handles length its own way.
• The chosen layout is captured once and printed twice, and both containers carry data-howto-design, so a variant with a different custom.how_to_design swaps the how_to_design_N class on the panel as well as its contents.
• The split layout composes an inline style from background-color, a background-image via image_url: width: 1600 and --d4s-text-color, per step.
• Step videos carry disablepictureinpicture and a poster from preview_image; sources are attached from data-src on first activation, load() is called once and the element is flagged so it's never reloaded.
• YouTube embeds pass enablejsapi=1 and the request host as origin, so play and pause commands can be sent to the frame by postMessage.
• Step titles become image alt text; the split layout falls back to the product title, then the accordion label.
• A second metafield, custom.how_to_use_2, feeds an accordion-style step list rendered beneath the slider layout through product-info-tabs-howto-design4.liquid.
• The drag slider locks to a horizontal gesture after 8px, commits a slide after 45px, and moves the track with translate3d; the grid slider only activates from 750px.

Edge Cases

• A step with neither image nor video still renders its title and copy.
• use_img_or_video left unset resolves to video when a video exists and no image does, otherwise image.
• One step means no track, no dots and no slider binding at all.
• Videos are paused when the mobile accordion closes, when the viewport crosses back to desktop, and when a step scrolls below a quarter visible.
• A bare YouTube id is accepted as an id when none of the four URL shapes match.
• With prefers-reduced-motion: reduce, or without IntersectionObserver, the scroll autoplay never binds; a rejected play() is swallowed rather than surfaced.

Platform Primitives Used

• Metaobjects — each step is a how_to_use metaobject; its media, copy, mobile variants and per-step colours are its fields.
• Metafields — custom.how_to_use holds the step list, custom.how_to_use_2 a second one, and custom.how_to_design the per-product layout override, variant first then product.
• Liquid section schema and settings — the layout select, the three split-layout defaults and the tab and accordion labels are section settings.

Integrations in Play

• YouTube — a step that chooses YouTube renders an embed built from the parsed id; the theme's play and pause helpers speak to it through the frame's JavaScript API.

Where It Runs

On the product detail page, inside the How To panel of the product information tabs, on all four product templates — standard, new-design, kids and waiting-list. Checked on the live storefront today: product pages render the slider layout with a lazily attached step video.

What This Demonstrates

• Brand story and editorial section system — the primary capability: four editorial presentations of one content model, each with its own art direction, chosen per product.
• Product education, how-to and routine content — application steps authored as structured records and rendered as a routine, a grid or a technique walkthrough.

How We Know

Six Liquid files read from the theme — the tabs snippet and the five How To snippets it renders — plus eight client-side records from spring 2026: three working-session notes and five product metafield exports. The records establish that the How To had to expand in place, with merchandiser control over its default state, a product-level selector between the four renderings documented in the metafield export, and a later scoping to show the How To only on products that have the content. The video handling, the observers and the capture-once mechanism are documented from the code.

Related Builds

• Metafield-driven product information tabs with mobile accordion and variant refresh — the container these layouts render inside, and the variant refresh that re-initializes them.
• Brand story split panel — the same storefront's image / hosted video / YouTube switch, at section level rather than per step.
• Responsive video hero with independent desktop/mobile sources — the same instinct about mobile video: a different file, not a rescaled one.
• Curl Quiz 3.0 — the same storefront's largest metaobject-rendered surface, where the records carry the logic as well as the copy.

The Buy-vs-Build Question

A how-to app stores the steps in the vendor's database and injects a fixed layout after paint. Building it bought steps in Shopify's own data model, four art-directed layouts switchable per product, and video that behaves on a phone — and cost a hand-built media path the theme has to maintain. Where owning the section vocabulary pays off is the subject of the theme section library and design system decision page.

Provenance & Evidence

• Client: LUS Brands — loveurcurls.com
• Surface: Product detail page
• Templates served: four — product, product.new-design, product.kids-new-design, product.waiting-list
• Complexity: High — roughly 650 lines across six Liquid files, most of it the four renderers and the playback script
• Attribution: Deploi-authored. The tabs snippet, the four layout renderers and the video snippet are ours. They run inside a theme built on Dawn 15.4.1 and subscribe to Dawn's variant-change channel through the tabs section.
• Status: Live, verified 2026-09-07
• Evidence: Six theme files plus eight client-side records — three working-session notes and five metafield exports — from spring 2026
• Confidence: Strong — the records document the four-way selector and the merchandiser control; the rendering and playback mechanics are documented from the code
• Primary capability: Brand story and editorial section system

Ready to Show Every Step the Way It Deserves?

You dream it. We build it. If your product instructions are one paragraph of text because the theme gave you nothing better, Contact us today and we'll show you what one step list can look like four ways.