Guides
Topic Explorer — Configuration Guide
Let customers browse topics and items in a drawer-based interface. Requires Metaobject setup in Shopify Admin before configuring.
Topic Explorer — Configuration Guide
This guide explains how to configure the Topic Explorer section in the theme editor. The section lets customers browse a set of topics, with each topic containing a list of items that open in a detail drawer. A brand-level description can also be shown in the optional "View All" tab.
Prerequisites
Before configuring the section, you must create two Metaobject definitions in Shopify Admin and populate them with entries. See Metaobject Setup Guide for the full setup guide.
In short:
- Go to Settings → Custom data → Metaobjects.
- Create the
topicandtopic_itemdefinitions. - Enable Storefront access on both.
- Create entries for your topics and items.
Location
- Theme editor: Add the Topic explorer section to any page template.
- Dedicated page template:
templates/page.topics.json - Section source: See sections/topic-explorer.liquid.
Section Settings
Layout
| Setting | Options | Default | Description |
|---|---|---|---|
| List variant | grid, list | grid | Controls how item cards are displayed. Grid shows compact cards in columns; list shows single-column rows with visible excerpts and larger thumbnails. |
| Grid columns (desktop) | 2–4 | 3 | Number of columns on desktop screens (grid variant only). |
| Grid columns (mobile) | 1, 2 | 1 | Number of columns on mobile screens (grid variant only). |
| Drawer position (desktop) | right, left | right | Which side the item detail drawer opens from on desktop. |
| Drawer mode (mobile) | bottom_sheet, full_screen | bottom_sheet | How the drawer appears on mobile. |
Content
| Setting | Type | Default | Description |
|---|---|---|---|
| Heading | Text | — | Section heading. Leave blank to hide. |
| Description | Rich text | — | Brand/section description shown only in "View All" mode. Supports bullet lists. |
| Description subheading | Text | — | Subheading rendered above the description text. |
| Description image | Image picker | — | Image shown alongside the description. Two-column layout on desktop, stacked on mobile. |
| Topics source | Select (all_topics, manual) | all_topics | all_topics pulls every topic metaobject automatically. manual lets you pick specific topics using blocks. |
| Default topic handle | Text | — | The handle of the topic to show first on load. If blank, the first topic (or "View all") is selected. |
| Enable "View all" | Toggle | Off | Shows a "View all" tab that displays items from every topic plus the description block. |
| Button label | Text | (translated default) | CTA text inside the item drawer. Leave blank to hide. |
| Button link | URL | — | CTA destination. Leave blank to disable the button even if a label is set. |
| Product | Product picker | — | Select a product. Its URL is used as the CTA link when no explicit Button link is set. |
| Button style | Select | primary | primary or secondary button styling for the drawer CTA. |
Style
| Setting | Type | Default | Description |
|---|---|---|---|
| Color scheme | Color scheme | scheme-1 | Controls the section's color palette. |
| Padding top | Select | medium | Top spacing: none, small, medium, large. |
| Padding bottom | Select | medium | Bottom spacing: none, small, medium, large. |
Topic Blocks (type: topic)
When Topics source is set to manual, add Topic blocks to choose which topics appear and in what order.
| Setting | Type | Description |
|---|---|---|
| Topic | Metaobject picker | Select a topic entry. |
Block order in the editor determines tab order on the storefront.
How It Works
- Topic tabs appear at the top of the section. If topics have hero images, tabs display as image cards with overlaid labels. Clicking a tab shows that topic's items.
- "View All" tab (when enabled) shows all topics' items and displays the description block (image + subheading + richtext). The description is hidden when viewing a specific topic.
- Topic panels show a hero image (if present) with a frosted-glass support card overlay listing the topic's support points. On mobile, the support card renders below the image. Title and intro text appear beside the image on desktop.
- Item cards display a circular thumbnail, title, and (in list mode) excerpt text.
- Clicking a card opens a drawer with the detail image, title, quick facts, body content, and sources.
- Prev/Next navigation inside the drawer (chevron icon buttons) follows the item order defined in the topic metaobject's
itemslist. - Deep linking is supported via URL parameters:
?topic=<topic_handle>&item=<item_handle>.
Empty-State Safety
- If no
topicentries exist, the section displays a "No topics found" message. - If a topic has no items, nothing renders for that tab.
- Missing images, excerpts, or body content are safely skipped — the section renders whatever is available.
- If JavaScript is disabled, topic tabs work as anchor links and item details expand inline via
<details>elements.
Practical Tips
- Image sizing: Use consistent aspect ratios for card images across items for a clean grid.
- Quick facts: Keep these short (3–5 bullet points). They appear prominently at the top of the drawer.
- Detail body: Supports rich text — use headings, paragraphs, and lists for structured content.
- Support points: For optimal rendering, use 3 support points per topic. Longer lists work on mobile (card flows below the image) but may crowd the desktop overlay.
- List variant: Best for smaller item sets or when excerpts add value. Grid works better for larger catalogues with visual thumbnails.
- Topic ordering: When using
all_topics, entries appear in the order Shopify returns them. For precise control, usemanualand add Topic blocks in the desired order. - Default topic: Set Default topic handle to your most important topic so it's visible immediately on page load.
- Description block: Use the description settings to provide brand-level context visible on the "View All" tab. The image and text render side-by-side on desktop.
Deep Linking Examples
- Show a specific topic:
https://yourstore.com/pages/topics?topic=ingredients - Open a specific item drawer:
https://yourstore.com/pages/topics?topic=ingredients&item=citric-acid
Handles must match the metaobject entry handles exactly (case-sensitive).
Troubleshooting
| Problem | Solution |
|---|---|
| Section shows "No topics found" | Create topic metaobject entries and enable Storefront access. |
| Drawer opens but content is blank | Check the topic_item entry has a title and/or detail_body. Verify the topic's items list references valid entries. |
| Deep links don't open the right item | Verify the entry handle matches the topic / item URL parameter exactly. |
| Topics appear in wrong order | Switch to manual and arrange Topic blocks in the desired order. |
| Description block not showing | Ensure "Enable View all" is on and at least one description field is populated. The block is visible only on the "View All" tab. |
| Support card overlaps image awkwardly | Keep support points to 3 items for best desktop overlay appearance. On mobile the card flows below naturally. |