Ingredient atlas

The ingredient atlas is not a list of one product’s contents. It is a library of every ingredient your brand uses, written once, that products using the same template draw from automatically in Product data mode. Each section instance has its own library; a separate template or another atlas section needs its own blocks.

That distinction is the whole design. Write hyaluronic acid once — its story, image, source, and type — and every product containing it on that template shows the same story, without you retyping anything.

The two modes

One section setting, Ingredient source, decides where the section gets its list.

Mode	What renders	Where to use it
Ingredient blocks (default)	The authored library, subject to the home-page limit	Home page, an ingredients page, brand storytelling
Product data	Only the ingredients that product declares	Product templates

Product data applies on product pages only. Placed anywhere else — a home page, a regular page — there is no product to read from, so the section uses the ingredient blocks instead. The home-page limit still applies. A regular ingredients page shows the full library.

The full walkthrough

Step 1 — tell Shopify what is in each product

Ingredient names come from a category attribute, so the product needs a category.

1. In Shopify admin, open a product.
2. Set Product category in the product organization card. Pick the most specific match.
3. Fill in Active ingredient on the product, one entry per ingredient.
4. Save.

By default the section reads Active ingredient. You can point it at Constitutive ingredients, Skin care features, or Ingredient origin instead using the Value source setting.

Step 2 — build the library

In the theme editor, add one Ingredient block per ingredient your catalog uses — not per ingredient in one product.

The Ingredient name on the block must match the name on the product. Matching ignores capitalization and punctuation differences, so Hyaluronic Acid on the block finds hyaluronic acid on the product. It does not match partially: Vitamin C will not find Vitamin C (Ascorbic Acid). Use the same wording Shopify offers on the product.

Fill in the rest of the block — type, image, story, source — once. Every product containing that ingredient inherits it.

Step 3 — switch the product template to product data

On your product template, open the section and set Ingredient source to Product data.

Each product now shows the matching ingredient stories from the library. Unmatched ingredients remain visible as names. The stories follow the order of your blocks, so drag blocks to set the reading order.

Step 4 — choose the home-page preview

On the home page, Maximum ingredients shows the first 5 blocks by default. Choose from 3–7 and move your most useful ingredients to the front. This limit applies in both source modes on the home page only; regular pages and product templates do not use it.

A filter only includes ingredients already shown by this limit. It does not reveal later blocks. Use a dedicated ingredients page when customers need to explore all 30 entries.

Add a Link to send customers from the preview to the full list, such as a page that uses the Ingredient index template. The link appears under the body text with the Link label you set, which defaults to View all ingredients. Leave Link empty to hide it. The demo home page shows five ingredients (Retinal, Niacinamide, Vitamin C, Hyaluronic acid, and Ceramides) and links to its Ingredient index page.

Optional: change ingredients automatically

Turn on Change ingredients automatically to move through the home-page ingredients on their own. Set Change ingredient every between 6 and 15 seconds; 10 is the default, which gives shoppers time to read each story. The setting applies on the home page only, so the ingredient index page never moves by itself.

A progress ring around the ingredient number on the image shows the time left before the next ingredient. The number is also the pause control: hovering or tabbing to it shows a pause icon, pressing it pauses the tour, and a play icon replaces the number until the shopper presses it again. The tour follows these rules:

• It pauses while a shopper points at a link or button in the section, such as an ingredient or a product, or has keyboard focus inside it. Resting the pointer on the rest of the section does not pause it.
• Each automatic change is a slow dissolve: the current ingredient fades out as the next fades in. It runs longer than a change a shopper makes, and still follows the theme’s Interface animation speed setting.
• The ingredient list scrolls to keep the current ingredient in view, but the page itself never scrolls.
• It pauses while the section is off screen, so the page never shifts under a shopper who has scrolled past.
• In the theme editor, the tour keeps running while the section is selected, so you can preview it. Selecting an Ingredient block shows that ingredient and holds the tour until you deselect the block.
• Choosing an ingredient stops the tour. The shopper can press play to start it again.
• It never runs when the visitor’s device is set to reduce motion; the ring is hidden and the number is shown on its own.
• Screen readers are not told about automatic changes. A change the shopper makes is announced as usual.

Filling in an ingredient story

Block setting	What to put there
Ingredient name	The name to match against product data
Ingredient type	A short category, such as Botanical or Mineral
Filter group	A broad benefit group, such as Hydration
Ingredient image and Image caption	An ingredient photograph and optional caption; a 4:5 image is recommended
Benefit summary	A short introduction to the ingredient’s role
First detail label / text	A labeled fact; the default label is Purpose
Second detail label / text	Another labeled fact; the default label is Source
Supporting note	Extra context in the note card; leave blank to omit the card
Supporting note icon	A built-in illustration, None, or a custom image
Reference text and Reference link	The source behind the story; the text becomes a link when a URL is supplied
First product, Second product, Third product	Up to three products to display under “Found in”

The “Found in” products are selected manually. Product data mode chooses ingredient stories; it does not search your catalog for related products. Check that each selected product actually contains the ingredient. With no products selected, the related-product row is omitted.

A reference link alone does not appear: fill in Reference text too. Remove the starter “Merchant-supplied ingredient note” text if you do not want a reference line.

For custom note icons, use a square transparent PNG or SVG. Tilt supporting note image rotates the illustration. Replace the preset stories with your own ingredient facts before publishing.

How customers explore the atlas

With JavaScript enabled, customers select an ingredient tab to show one story at a time. On desktop at widths of 990px and above, the ingredient index sits in a sticky left column and scrolls vertically when needed. Below that width, the tabs form a horizontal row.

On phones, customers can also swipe across the ingredient image or story to move between the visible ingredients. Swiping a related-product row scrolls its products instead. Keyboard users can move through ingredient tabs with the arrow keys, Home, and End.

Without JavaScript, the ingredient stories remain visible in sequence. Filters and tab switching are enhancements, so the content does not depend on them.

What renders in each situation

Product mode has four outcomes, and all four are intentional:

The product…	What a customer sees
lists ingredients, all in the library	A full card for each one
lists ingredients, some not in the library	Cards for the matches, plus the remaining names as a plain list
lists ingredients, none in the library	The names as a plain list, no cards
lists no ingredients at all	Nothing — the section is hidden

That last row matters. A product that declares no ingredients does not borrow the library’s, because that would claim contents the formula may not have. The section stands down instead.

The theme editor shows notes when product data is selected outside a product page, when the product has no ingredient data, and when some matched stories have unmatched names alongside them. A names-only result has no separate missing-library note: compare those names with your blocks.

Ingredients the library has no entry for still appear as names. The list stays truthful rather than quietly dropping them. Add matching blocks to turn those names into stories.

The 30-ingredient cap

The section holds 30 Ingredient blocks. This limits the number of authored stories in one section instance. Product data can still list more names: ingredients without a matching block appear in the plain list. The home-page preview has its separate 3–7 limit.

Thirty covers a focused skincare range comfortably. If you are pressing against it:

• Build the library around actives, not every excipient. Nobody reads the twenty-eighth card, and the ingredients that carry your claim get buried.
• Split by range. Use a second atlas section on a different template rather than one library serving unrelated product lines.
• Review unused entries. In Product data mode they never match; in Ingredient blocks mode they can still serve your brand story.

Filter groups

Each block has a Filter group. Matching ignores capitalization and normalizes punctuation, so use consistent wording for ingredients that belong together.

The filter row appears only when Show filter groups is enabled, more than one ingredient story renders, and at least one of those ingredients has a nonblank group other than All. Names-only lists do not have filters. Groups belonging only to excluded ingredients do not appear.

Use a handful of broad groups — Hydration, Barrier, Brightening — rather than one per ingredient. A filter row where every filter shows a single card is not a filter.

Leave the field blank and the ingredient still shows under All. All is reserved for the complete visible set, so use another name for a specific group.

Styling the section

• Content size scales the heading, ingredient names, body text, and benefit summaries together.
• Mobile header alignment follows the theme setting by default, or can be set to Left or Center. It also aligns filters and ingredient tabs; wide tab rows remain scrollable.
• Image shape offers Arch, Portrait, or Organic. Ingredient image width adjusts the balance between image and details on tablet and desktop, from 44–66%.
• Index illustration adds a built-in illustration or your own transparent SVG or PNG. Rotation and horizontal shift position it. An uploaded image’s background is preserved.
• Color scheme sets the section colors. Note and product colors can inherit them or use a separate Note and product color scheme for supporting notes and related products.
• Show ingredient numbers controls numbers in the tabs and names-only list. The image and story retain their specimen numbers.
• Show entrance animation works with the theme’s scroll-reveal setting and respects reduced motion. Tab transitions follow the theme’s interaction motion settings.
• Top spacing and Bottom spacing set desktop spacing; mobile uses 60% of those values.

The section can be added to page and product templates, but cannot be placed in header or footer groups.

Using it well

• Write the library once, properly. This is the section with the best effort-to-payoff ratio in the theme, because every entry is reused across every product containing it. Time spent on a card is spent once.
• Keep the intro short. One or two sentences. The ingredients are the content.
• Match Shopify’s wording exactly when naming blocks. Most gaps come from a block named slightly differently from the attribute value.
• Check a phone. Verify the ingredient tabs scroll, the stories are readable, and swiping the story and the related-product row does what you expect.
• Avoid duplicate ingredient names. Product data mode uses the first matching block only. Ingredient blocks mode shows both, subject to the home-page limit.

When an ingredient does not appear

Work down this list:

1. The name does not match. The most common cause by far. Compare the block’s Ingredient name with the value on the product, character for character.
2. The product has no category, or Active ingredient is empty. No data, nothing to match.
3. Ingredient source is still on Ingredient blocks. The section is showing the whole library, not the product’s.
4. You are pointed at the wrong attribute. Check Value source matches the field you filled.
5. A duplicate block. In Product data mode only the first matching entry renders.
6. The home-page limit. Ingredients after Maximum ingredients are excluded, even from filters.
7. An active filter. Select All to restore the visible ingredient set.
8. A hidden filter row. Enable Show filter groups and check that at least two stories render, with a valid group on at least one of them.