App Integration
Peregrine is built to get out of an app's way: kill switches that remove the theme's own output cleanly, stable data hooks for scripts to latch onto, and app block support in the right places.
Kill switches — clean handover, not co-existence
Where an app category competes with something the theme ships, Peregrine gives you a master switch that removes the theme's version entirely — no hidden markup, no leftover scripts, nothing for the app to fight. Off means off in the page source, not just hidden.
| Switch | Where | Turn it off when you install… |
|---|---|---|
| Enable theme SEO output | Theme settings → SEO | An SEO app that injects its own structured data — avoids duplicate JSON-LD, the classic Shopify schema conflict. Granular per-type toggles sit under the master. |
| Enable filtering | Theme settings → Filtering | A third-party filter app. The server-rendered product grid remains as a clean surface for it to enhance. |
| Enable product badges | Theme settings → Product badges | A badge or product-label app — the card corner is theirs alone. |
| Enable predictive search flyout | Theme settings → Search | An instant-search app. The header's search icon becomes a plain link to the search page and the flyout's script never loads. |
Stable data hooks
These attributes and classes are a documented surface — they keep their names across theme updates, so scripts built against them won't break:
| Hook | Where | What it identifies |
|---|---|---|
data-product-id, data-product-handle | Every product card's root element | The product a card represents — for quick-view, wishlist and review apps |
data-collection-grid | The collection page product grid | The element filter apps should re-render or observe |
.product-badge, .product-badges | Product cards | The theme's badge elements (absent entirely when badges are switched off) |
App blocks
The collection page accepts app blocks between its toolbar and product grid — the slot collection apps expect — and the product page's block-based architecture accepts them the same way.
- Install the app from the Shopify App Store first. An app block cannot appear in the theme editor until its app is installed.
- Open the theme editor and switch the page selector to the template you want — Collection or Product.
- Select the section in the left-hand list, then click Add block.
- Choose the app's block from the Apps group at the bottom of the picker. If the group is missing, the app has not published a block for this template — check its own documentation.
- Drag it to where you want it and Save. On the collection page it lands between the toolbar and the grid wherever you drop it.
An app block belongs to the app, not the theme. If you uninstall the app the block stops rendering, and its appearance is controlled by the app's own settings rather than the theme's — so it will not necessarily inherit your colours and fonts.
Events
Cross-component communication uses DOM CustomEvents rather than shared state. peregrine:variant:change fires on the product page whenever the selected variant changes — listen for it to react to variant switches without touching theme internals.