Extension System¶
Transform your e-commerce experience with Badger Commerce's powerful extension system. Add new features, customize your storefront, and create unique customer experiences—all without modifying core platform code.
What Are Extensions?¶
Extensions are self-contained modules that add functionality to your store. Think of them as apps for your e-commerce platform. Whether you need seasonal effects, social proof, advanced search, or payment integrations, extensions let you compose the perfect experience for your customers.
Why Extensions?¶
🚀 Fast Deployment Add new features in minutes, not weeks. No core platform changes required.
🎨 Customization Without Code Changes Business users can configure extensions through an intuitive admin interface.
🔄 Theme-Agnostic Extensions work across all themes: Nova, the themes layered on it, and custom themes.
📊 Data-Driven Built-in analytics show how extensions impact conversion and engagement.
🔌 Mix and Match Combine multiple extensions to create unique customer experiences.
Real-World Extension Examples¶
🎄 Christmas Mode¶
Add festive magic to your store during the holidays: - Falling snowflakes with realistic physics - Snow accumulation on product cards - Subtle festive color accents - User-controlled disable option
Perfect for: Seasonal campaigns, holiday shopping experiences, brand personality
🔥 Trending Products¶
Show customers what's hot right now: - Real-time tracking of popular products - Configurable time windows (last 24h, 7 days, etc.) - Automatic updates based on user behavior - Placement anywhere on the site
Perfect for: Social proof, discovery, cross-selling
🎠 Interactive Carousels¶
Showcase your best content with rich media carousels: - High-quality image and video support - Auto-play with configurable timing - Mobile-optimized touch gestures - Call-to-action overlays
Perfect for: Hero sections, featured collections, storytelling
💳 Apple Pay¶
Enable frictionless checkout: - One-click purchasing - Secure tokenized payments - Express checkout from product pages - Cart and checkout integration
Perfect for: Mobile conversion, premium customers, impulse purchases
🔍 Algolia Search¶
Supercharge product discovery: - Instant search results - Typo tolerance - Faceted filtering - Personalized ranking
Perfect for: Large catalogs, complex product hierarchies, power users
Extension Categories¶
📦 Product & Catalog¶
Enhance how customers discover and view products: - Product Galleries: Interactive image viewers with zoom and 360° views - Quick View: Modal product previews without page navigation - Size Guides: Interactive sizing tools and fit finders - Product Bundles: "Complete the look" suggestions - Stock Notifications: Back-in-stock alerts and waitlists
🛒 Checkout & Payments¶
Streamline the path to purchase: - Express Checkout: Apple Pay, Google Pay, PayPal - Address Validation: Real-time address verification - Gift Options: Gift wrap, messages, and delivery scheduling - Discount Displays: Smart coupon suggestions - Order Confirmations: Enhanced post-purchase communication
🎨 Content & Marketing¶
Tell your brand story: - Hero Carousels: Full-width image and video sliders - JSON Components: AI-assisted custom UI with semantic styling and data binding - HTML Fragments: Custom content areas with rich formatting - Video Embeds: YouTube, Vimeo, and native video - Testimonials: Customer reviews and social proof - Blog Integration: Editorial content alongside products
🧭 Navigation & Discovery¶
Help customers find what they need: - Mega Menus: Rich navigation with images and categories - Breadcrumbs: Clear path tracking - Collection Choosers: Visual category selection - Faceted Search: Filter by attributes, price, brand - Related Products: AI-powered recommendations
👥 Social & Engagement¶
Build community and trust: - Product Reviews: Star ratings and written feedback - Social Sharing: One-click sharing to social platforms - User Photos: Customer-generated product images - Live Chat: Real-time support integration - Wishlists: Save for later functionality
🎯 Personalization¶
Deliver tailored experiences: - Geolocation: Region-specific content and offers - User Segments: Show different content to different audiences - A/B Testing: Compare extension performance - Behavioral Targeting: Content based on browsing history - Recommendations: Personalized product suggestions
🎪 Seasonal & Special Events¶
Celebrate moments that matter: - Christmas Mode: Festive effects and theming - Valentine's Day: Romantic overlays and gift guides - Black Friday: Countdown timers and urgency indicators - Flash Sales: Limited-time offer banners - Anniversary Celebrations: Brand milestone features
How It Works¶
For Business Users¶
-
Browse Extensions Visit the extension library in your admin panel
-
Configure Settings Use the visual editor to customize behavior
-
Place Extensions Drag and drop extensions into page slots
-
Preview & Publish See changes before customers do
-
Monitor Performance Track engagement and conversion impact
For Developers¶
-
Create Extension Class Extend base classes with your logic
-
Design Templates Build Thymeleaf templates for rendering
-
Add Resources Include CSS/JS for interactivity
-
Register Extension Spring Boot auto-discovers your extension
-
Test & Deploy Use built-in testing utilities
👉 Developer Guide: See /docs/developers/building-extensions.md for detailed technical documentation
How blocks reach the page¶
A page is made of slots (topBanner, mainSection, bottomBanner, navMenu, footer and the
rest), each holding the blocks placed in it, in displayPriority order (lower numbers first). Every
theme draws every slot through one shared fragment, ui/slot, which puts each block in its own
wrapper element (<div class="bdgr-block">) around the block's template. The wrapper has no box of
its own, so pages look exactly as they did without it; it is where colour schemes and the visual
section editor attach to a block. When staff look at a page (the admin's Content blocks tab, inline editing or a
page preview), each wrapper also says which block it is (data-bdgr-block, data-bdgr-extension,
data-bdgr-slot); shoppers' pages don't carry those attributes. See
Building extensions.
Extension Composition¶
Combine extensions to create powerful experiences:
Example: High-Converting Product Page
┌─────────────────────────────────────┐
│ [Breadcrumbs Extension] │
├─────────────────────────────────────┤
│ [Product Gallery Extension] │
│ + [Size Guide Extension] │
├─────────────────────────────────────┤
│ [Product Reviews Extension] │
├─────────────────────────────────────┤
│ [Trending Products Extension] │
├─────────────────────────────────────┤
│ [Recently Viewed Extension] │
└─────────────────────────────────────┘
Example: Festive Homepage
┌─────────────────────────────────────┐
│ [Christmas Mode Extension] │ ← Global effects
├─────────────────────────────────────┤
│ [Hero Carousel Extension] │ ← Holiday messaging
├─────────────────────────────────────┤
│ [Featured Collections Extension] │ ← Gift guides
├─────────────────────────────────────┤
│ [Email Capture Extension] │ ← Holiday newsletter
└─────────────────────────────────────┘
Built-In Extensions¶
Badger Commerce includes a rich library of pre-built extensions:
| Extension | Category | Use Case |
|---|---|---|
| Christmas Mode | Seasonal | Holiday atmosphere |
| Trending Products | Social | Social proof |
| Static Carousel | Content | Hero sections |
| Hero | Content | Hero sections from five presets, with optional eyebrow, second button and stats and an animated background |
| Call to Action | Content | An appeal band, strip, sidebar panel or stat, edited as a form |
| JSON Component | Content | AI-assisted custom UI |
| Apple Pay | Payments | Express checkout |
| Algolia Search | Discovery | Fast search |
| Product Gallery | Product | Image viewing — selectable layout modes |
| Featured Product | Product | Merchandising products — selectable display modes |
| Collection Product Grid | Product | A collection page's products, as a placeable block |
Related Products (relatedProducts) |
Product | "You may also like" below a product's details: products that share its collections or taxonomy category. On the product stereotypes by default |
Event Details (eventDetails) |
Product | When and where an event is, doors open, ticket status and an add-to-calendar link, on an event's product page. Carried by the eventProduct stereotype |
| Facet Display | Navigation | Filtering |
| HTML Fragment | Content | Custom areas |
| YouTube Video | Content | Video embedding |
| Menu Generator | Navigation | Site navigation |
| Social Links | Social | Social integration |
| Donation Display | Social | Recent donations and donors' messages as a static list or a paged, cross-fading carousel (scrolling / rotating) with pause, previous and next controls, pausing on hover and focus and still for reduced motion; see Donation Display. The Ridge theme keeps its own rotating ticker (nova/js/donation-ticker.js) |
| Contact Forms | Engagement | Customer inquiries |
| Email Capture | Marketing | Newsletter signup |
| Personal Details | Checkout | Customer info |
Product Gallery Modes¶
The Product Gallery extension renders a product's images in one of several layouts, chosen from a Gallery Mode picker in the extension's admin settings (Nova theme):
| Mode | Best for | Behaviour |
|---|---|---|
| Carousel (default) | Single-hero products | Main image with a synced thumbnail strip, zoom lightbox and hover-zoom |
| Fashion Grid | Apparel & lifestyle | Responsive grid of every photo, each one click-to-zoom and hover-zoom |
| Spotlight + Filmstrip | Detail-rich products | One large image with a vertical thumbnail filmstrip (horizontal on mobile) |
| Editorial Stack | Lookbooks & storytelling | Full-width images stacked in a single scrolling column, each zoomable |
All modes share the same PhotoSwipe lightbox and support variant-aware image switching, so the
gallery updates automatically when a shopper selects a different variant. New modes can be added
with a single GalleryMode enum entry plus a matching Thymeleaf fragment.
Featured Product Display Modes¶
The Featured Product extension merchandises a set of products — a fixed list of SKU IDs, a named collection, or the current collection when Use Page Context is on — in one of three layouts, chosen from the Display Mode picker:
| Mode | Best for | Behaviour |
|---|---|---|
| Carousel (default) | Hero banners | Full-width slideshow, one product at a time, with a slow image pan |
| Grid | Compact rows | Horizontally scrolling row of product cards |
| Cover Flow | Browsing a range | 3D strip of cards you drag through, centre card foremost |
Cover Flow¶
Cover Flow is built for scrubbing rather than stepping. Cards are dragged with the mouse or a finger and carry momentum on release, so a flick crosses several products and a nudge settles back. Vertical scrolling always belongs to the page — the strip only claims a gesture that is clearly horizontal — and arrows, indicator bars and the left/right keys all still work.
Titles and prices stay legible on the cards either side of the centre, not just the middle one. Only the centre card's View Details button is live. Clicking or tapping a card off to the side brings it to the centre instead of opening it. The button stays dead while the strip is travelling, so a flick can't carry live buttons past under a finger, but it wakes up on the final approach, within a quarter of a card of rest. A tap on a card that is all but home opens it rather than being rejected. Touching the strip mid-glide catches it, and releasing without a drag lets it finish settling on the nearest card.
Two settings shape it:
- Cover Flow Looping —
Auto(the default) wraps around once there are five or more products, and stops at the ends below that, where a wrapping card would have to fade out almost at the centre.Always wrap aroundandNever wrapforce either behaviour. - Maximum Number of Products — set to
0to load the whole collection (capped at 250) and get a catalogue-flicking strip rather than a short highlight reel. Cover Flow only ever paints the handful of cards near the centre, so a long strip stays smooth; the indicator dots are dropped past a dozen products, where they stop being a useful position readout.
Collection Product Grid¶
A collection page's product grid (the title, sort row, sub-category links, product cards and
pagination) is the collectionProductGrid extension. That means it can be moved, hidden or
restyled per collection or per stereotype, from the admin extension panel or by an AI agent through
the MCP manageExtensionConfig tool, like any other block.
It's opt-in. A collection page renders its long-standing built-in grid unless
collectionProductGrid renders on the page, whether it's configured on the collection itself or
inherited from the collection's stereotype. The built-in grid and the extension share one fragment
per theme (fragment/collection-product-grid), so with default settings the page looks exactly as
before. Existing sites are unchanged. New sites get the extension through the defaultCollection
stereotype (initialisation/default/stereotypes.json).
Where it renders. Its default slot is productGrid, between topBanner and bottomBanner on
the Nova and Brock collection templates. It can also be placed in topBanner
or bottomBanner. Anywhere else it wouldn't be seen, so the built-in grid stays.
| Setting | Default | Effect |
|---|---|---|
showProducts |
true |
false hides the whole grid |
showTitle |
true |
Show the collection name as the heading |
showSort |
true |
Show the "Sort by" control |
showSubcategories |
true |
Show links to child collections and up to the parent (Nova, Brock) |
columns |
0 |
Products per row on desktop, 2–6. 0 keeps the theme's responsive layout. Phones and tablets are unaffected |
pageSize |
0 |
Products per page, 1–100. 0 inherits (see below) |
Hiding products. The collection's admin-only Hide Products checkbox still hides the grid,
whether it's built in or comes from the extension. To hide the grid through extensions on one
collection whose stereotype places it, add collectionProductGrid to that collection in the same
slot with showProducts=false. An item-level placement replaces the stereotype's placement of the
same extension in the same slot. Disabling the collection-level placement doesn't work, because a
disabled placement doesn't suppress the stereotype's.
Page size, most specific first:
pageSizeon acollectionProductGridplaced on the collection itself- the collection's
pageSizeOverrideconfiguration property pageSizeon the stereotype'scollectionProductGrid- the site's
defaultCollectionPaginationPagesSizeconfig (default 12)
View-only by design. CollectionController still fetches, sorts and paginates the products.
The extension's template only lays out the page model (products, paginationParams,
sortingBean, collection, childCollections). The one setting the controller reads up front is
pageSize, through ExtensionService.findEffectiveConfiguration. Sorting, pagination and the AJAX
re-sort all behave as before, because the grid still renders inside
#ajax-body. After rendering the extensions, the controller sets productGridExtensionRendered
when the extension's model (marked collectionProductGrid: true) landed in one of the page's grid
slots, and the templates skip their built-in grid on that flag.
Related Products¶
relatedProducts is a "You may also like" rail of other products, shown below a product's details
(its default slot is lowerBannerSlot). It is on by default: new shops get it on the
defaultProduct and variantProduct stereotypes (initialisation/default/stereotypes.json), and the
system update 2026-11-16-add-related-products-to-product-stereotypes added it to existing shops'
defaultProduct and variantProduct stereotypes, except where a stereotype already had a
relatedProducts block. A shop that doesn't want it removes it from the stereotype; one product can
drop it by deleting the inherited block from that product.
Where the lists come from. Each product has stored lists of related products, kept apart from the product itself. Providers fill them, and the product page only reads them: nothing is ranked and no stock is checked while the page renders. A list is as fresh as its provider last made it, so a newly created product shows nothing, and a product whose collections changed shows its older list, until its list is next generated. Staff-picked lists (planned) will win over generated ones; otherwise the most recently generated list is shown.
How Badger generates its lists. Badger's own lists are generated by a background job in the worker, in two ways:
- Nightly, at 03:45 by default (after the nightly search jobs), for every shop: every enabled product's list is worked out again. Only the lists that changed are written, and a list that is no longer warranted (the product now shares nothing with any other, or was disabled since) is deleted. One worker runs it at a time.
- Soon after a product is created or changed: within about a minute, that product gets its own list. Saves are gathered for 20 seconds, so an import is handled in one go, each product once; when more than 500 products changed together, the whole shop's lists are worked out again instead. Other products' lists that should now include the changed product catch up on the next nightly run.
Badger ranks products by what they share with the product: the more of its collections another product is in, the higher it ranks; being in the product's main (primary) collection counts as one more, and so does being in the same taxonomy category (the category the product is classified under in the shop's product taxonomy). Ties go to the newest product. A list holds at most 24 products. The category is what makes the rail work in a shop organised by a category tree built from its taxonomy, where products are often in no collection at all; together with the main collection it stands in for the product's home category in the tree, which isn't looked up separately. A product in no collection and no taxonomy category has no related products: the rail never falls back to unrelated or random products. Products that a plan's product limit holds back are never listed.
Two limits keep the lists meaningful and the job fast:
- Broad groups are ignored. A collection or taxonomy category holding more than half of the shop's enabled products, and more than 200 of them, says nothing about which products are alike ("All products", "Sale"), so it doesn't count towards relatedness (nor as a main collection). A collection or category of 200 products or fewer always counts, so small shops are unaffected.
- Only the 2,000 newest products of any one collection or category are considered through that group. An older product can still be listed through another collection or category it shares.
| Property | Default | Effect |
|---|---|---|
badger.related-products.enabled |
true |
false stops both the nightly run and the updates after product changes; stored lists stay as they are |
badger.related-products.cron |
0 45 3 * * * |
When the nightly run starts (server time, UTC) |
badger.related-products.fill-missing-interval |
PT1H |
How often the worker looks for shops that haven't had a whole-shop run in the last 36 hours (a new shop, one just moved here or reseeded, whose product saves gave only those products lists, or one whose nightly run failed) and runs them without waiting for the nightly run; the first look is two minutes after start-up (fill-missing-initial-delay). Every whole-shop run, nightly or not, resets the 36 hours |
What's left out when the page reads the list. The product itself, products that no longer exist, disabled products, products the shopper may not see (in staff-only collections only) and events that have ended. Stock is not checked: the product page and basket check it. When nothing is left, the rail renders nothing, not an empty heading.
| Setting | Default | Effect |
|---|---|---|
heading |
blank | The rail's heading. Blank uses the shop's wording, the Site Text key ui.rail.related ("You may also like") |
numberOfProducts |
8 |
The most products shown, 1 to 24. Desktop shows the first five in a row; phones and tablets swipe through all of them |
Rendering. Every theme uses Nova's one template, which draws the shared rail (ui/rail.html)
with the theme's own rail card (productFragment/railCard), so the rail matches the theme's other
product rails. Reading a product's list costs two small database queries: its stored lists, then the
listed products in one go, read without their variants or description
(ProductService.findCardsByIdInAndSite). The rail's cards show neither, and in a shop whose products
each have many variants those fields are most of each product, and most of the cost of reading it.
Storage. The lists live in their own productRelations collection (one per product, list type
and source), read and written through ProductRelationService. A product's lists are deleted with
the product, and a site's with the site. They are not part of a site transfer:
the target shop generates its own.
Hero optional slots¶
Besides title, subtitle, cta (and heroImage on Split Image), every preset can show three
optional slots. Each is a JSON component like the others, and is drawn only when the heroConfig
has it:
| Slot | Component | Where it shows |
|---|---|---|
eyebrow |
text |
A short line above the title |
secondaryCta |
button |
A second button beside cta (centred presets centre both) |
stats |
any, usually a row of columns each holding a heading (the figure) and a text (its label) |
A strip of figures under the buttons |
{"preset": "gradient", "backgroundImage": "media/team.jpg", "slots": {
"eyebrow": {"type": "text", "props": {"text": "Volunteers on call right now", "style": {"variant": "body-sm", "transform": "uppercase", "tracking": "widest"}}},
"title": {"type": "heading", "props": {"text": "On call 24/7, 365 days a year", "level": 1, "style": {"variant": "heading-xl", "color": "white"}}},
"cta": {"type": "button", "props": {"text": "Make a donation", "action": {"type": "navigate", "href": "/product/donate"}, "style": {"variant": "button-primary"}}},
"secondaryCta": {"type": "button", "props": {"text": "Recent callouts", "action": {"type": "navigate", "href": "/p/callouts"}, "style": {"variant": "button-secondary"}}},
"stats": {"type": "row", "children": [
{"type": "column", "children": [{"type": "heading", "props": {"text": "83", "level": 3}}, {"type": "text", "props": {"text": "callouts so far this year"}}]},
{"type": "column", "children": [{"type": "heading", "props": {"text": "100%", "level": 3}}, {"type": "text", "props": {"text": "volunteer team, unpaid"}}]}
]}
}}
The admin form has fields for the eyebrow and the second button (each is added when filled in and
removed when cleared); stats are set in the JSON editor. The markup is in
nova/extensions/hero/slots.html, shared by the five presets. The presets carry no inline styles:
their layout and surfaces are in Nova's bdgr.css ("ui: hero"), and a theme restyles them through
--hero-* tokens (the stats rule, the accent line, the overlays, surfaces and heights; the full list is
in the header of nova/extensions/hero/main.html). Ridge, for example, sets --hero-stats-rule and
--hero-accent. A hero's own photo and colours reach the page as --hero-bg-image, --hero-bg and
--hero-text on the section.
Call to Action¶
The callToAction extension is a call to action edited as a form, so a site doesn't hand-write HTML
for an appeal or a "join us" strip. Its fields are Style, Eyebrow, Heading, Text (line
breaks kept), Figure, and up to two buttons (Button Text/Link, Second Button
Text/Link). A button shows only with both its text and a link, and a link must be a site path
(/p/about), an anchor, or an http(s), mailto: or tel: link, so nothing the browser would run
as script gets through.
| Style | Looks like | Suits |
|---|---|---|
band |
Full width in the brand colour, light buttons | A page-wide appeal or announcement |
strip |
A card with the text on one side and the buttons on the other; in a full-width slot (topBanner, bottomBanner, bannerSection) it keeps the page width |
Between sections |
panel |
A compact card with full-width buttons | A sidebar, e.g. beside a blog post |
stat |
One large figure, its label (the eyebrow) and a link | A sidebar |
Nova draws it for every Nova-based theme (nova/extensions/callToAction/main.html) in the theme's
colours, and a theme with its own look overrides
extensions/callToAction/main (Ridge draws its appeal band, strip, panel and stat). Its heading and
text are indexed for site search (CallToActionContentExtractor).
Hero Height¶
A hero is a landing hero by default: at least 70% of the screen tall ("height": "tall"). For the
banner at the top of an inner page, choose Height → Compact in the hero's admin Background section,
or set "height": "compact" in the heroConfig JSON. A compact hero is as tall as its text, with the
same padding as a blog post's masthead, so inner pages and blog posts open the same way; keep the tall
hero for the home page. Every preset supports it, and the setting stays when you switch preset.
For a photo-led home page, Height → Full screen ("height": "screen") fills the rest of the window
under the nav (100svh less --nova-hero-screen-offset, 72px by default, so a phone's collapsing
address bar doesn't push the bottom off screen and slideshow controls stay in view). A theme with a
taller nav sets that variable to its height, and one whose header floats over the hero sets it to 0.
Hero Slideshow Background¶
The Centered and Gradient Overlay presets can fade between several photos behind their copy: the
title, text and buttons stay put while the background changes. In the hero's admin Background
section, Add photos picks them from the media library (several at once); each gets a short
caption shown beside the controls and a description (alt text). Through MCP they are keys in
the heroConfig JSON:
| Key | Values | Default |
|---|---|---|
backgroundImages |
[{"url", "caption", "alt", "focalPoint"}, ...]: two or more make a slideshow; a single one is used as backgroundImage when that is empty |
none |
focalPoint |
Where to crop backgroundImage around (also on each backgroundImages entry): "x y" percentages from the top left, or top / center / bottom. Without it the media item's own focal point is used, else the centre |
none |
slideInterval |
Milliseconds each photo shows, clamped to 3000–20000 | 6000 |
slideControls |
both (caption with "2 of 5", arrows, dots), dots, arrows, none; the pause button is always there. On a phone both drops the dots (the caption gives the place) and dots wraps |
both |
{"preset": "centered", "height": "screen", "backgroundOverlay": "dark",
"backgroundImages": [{"url": "https://images.bdgr.co.uk/shop/media/a.jpg", "caption": "Drone ops", "alt": "..."}, ...],
"slots": {...}}
An address must be a path on the shop or an http(s) / protocol-relative one; anything else is
dropped. The other presets ignore the photos (Split Image has its own image, Video Background its
video, Minimal a plain surface), and they stay in the config when you switch between Centered and
Gradient Overlay.
How it renders. nova/extensions/hero/slideshow.html stacks the photos as <img> elements under
the overlay (the first eager with fetchpriority="high", the rest lazy) and draws the controls above
the bottom fade on a dark translucent pill, so they read on light and dark themes. nova/js/hero-slideshow.js
(deferred, loaded only by a hero with a slideshow) cross-fades them. It pauses while the pointer or
keyboard focus is in the hero and when the tab is hidden, and stops for good once the visitor presses
pause or picks a photo. Visitors who prefer reduced motion get no autoplay. Swiping left or right
changes photo on a touch screen. Captions are announced only once the visitor is driving it, never
while it rotates by itself. Without JavaScript the first photo shows. The control labels are the
shared carousel.* messages.
Use the Static Carousel (staticCarouselExtension, see Content Management) instead when each slide carries its own text or link;
the hero slideshow is for one message over changing photos.
Hero Content Alignment¶
The Gradient Overlay and Split Image presets set their copy on the left. By default it starts a fixed
distance from the window's edge ("contentAlign": "edge"), which on an ultrawide screen leaves it far
to the left of the logo and the page below. Choose Content alignment → Page content in the hero's
admin Background section, or set "contentAlign": "container", to line the copy up with the page's
content column (the theme's --container-max-width and --container-padding). Below 1024px both
look the same. The setting stays when you switch preset; the centred presets ignore it.
Hero Background Effects¶
The hero extension (five presets: Centered, Split Image, Video Background, Gradient Overlay,
Minimal) can draw an ambient animated background behind its copy, in the style of the Stripe and
Accenture homepages. It is off by default, so existing heroes are unchanged. Set it in the hero's
admin Background section (Animated effect, Level and the Fine-tune sliders), or through
MCP (manageExtensionConfig) as keys in the heroConfig JSON:
| Key | Values | Default |
|---|---|---|
backgroundEffect |
none; constellation (drifting points joined by lines, scattered by the pointer); flowField (particle trails following a noise field, swirling round the pointer); terrain (a wireframe landscape rolling towards the viewer: the ground rises under the pointer and a click sends a ripple across it); globe (a dotted globe with shipping arcs from the shop, which visitors can drag to spin); aurora (large soft fields of brand colour that lean towards the pointer); gridGlow (a perspective dot grid with a travelling glow) |
none |
backgroundEffectIntensity |
subtle, normal, present, bold, showpiece: how strongly it draws |
present |
backgroundEffectTuning |
Optional overrides of the level, each clamped: strength 0.2–4, speed 0.25–4, density 0.4–2.5, size 0.5–3.5, pointer 0–4, behindCopy 0–1 (how much shows behind the text), linkDistance 0.5–2.2 (constellation), trail 0.3–4 (flow field), relief 0–3 (terrain) |
none |
globe |
For the globe: {"home": {"lat", "lon"}, "destinations": [{"lat", "lon"}, ...]}. Arcs fly from home to each destination (up to 24). With a home and no destinations they go to major cities worldwide; with no home the globe spins without arcs |
none |
{"preset": "gradient", "backgroundEffect": "terrain", "backgroundEffectIntensity": "bold",
"backgroundEffectTuning": {"relief": 1.6}, "slots": {...}}
Levels and sliders. A level sets every value at once; a slider overrides one of them and leaves the rest following the level. Subtle and Normal are the original, quieter levels, and a hero saved with one of them keeps it. Bold and Showpiece suit a short headline with room around it; behind long copy, keep Present or lower. In the admin, Reset to the level removes the overrides. The values behind each level are in Hero motion.
Where it draws. Gradient Overlay (light marks on the dark brand gradient), Minimal (brand-tinted marks on the light surface) and Split Image (behind the text column only). Centered and Video Background already carry a photo or video, so they ignore the setting.
How it renders. The template (nova/extensions/hero/background-effect.html, used by Brock and
the other Nova-layered themes too) inserts an aria-hidden <canvas> with pointer-events: none
between the background layers and the content, and loads nova/js/hero-background.js with defer
only when a hero on the page uses an effect. The script is plain JavaScript with no libraries:
- Colours follow the Design Brief. It resolves
--color-primary,--color-secondary,--color-accentand--color-on-dark-accentat runtime, so each tenant's palette restyles it. - Text stays legible. A CSS mask fades the canvas out behind the copy (to the left on Gradient and Split Image, the centre on Minimal), by as much as the level's "shows behind the text" value says. The content sits above the canvas.
- Pointer, drag and click. The pointer is tracked on the hero section. The globe is dragged and terrain ripples on a click, but a press on the hero's own links, buttons and fields is left alone, and on a touch screen vertical swipes still scroll the page.
- Reduced motion. Under
prefers-reduced-motion: reduceit draws a single still frame and never animates. - Cheap when idle. It pauses when the hero scrolls offscreen (IntersectionObserver) or the tab is hidden, sizes the canvas for the device pixel ratio (capped at 2) with a ResizeObserver, and scales the particle count with the hero's area, capped lower on phones.
Hero Entrance¶
Every hero preset can animate its copy in when the page loads: the eyebrow, title, text, buttons and
stats arrive one after another. Set it in the hero's admin Entrance section, or with these
heroConfig keys:
| Key | Values | Default |
|---|---|---|
entrance |
auto (Fade up on Centered, none on the other presets, as heroes always did); none; fadeUp (a short fade up); rise (a longer rise with a soft landing); blur (sharpens into place); wipe (each line revealed from below); settle (scales down slightly into place); words (the title arrives word by word) |
auto |
entranceTuning |
Optional: travel 0–140 (pixels each line moves), duration 0.2–2.5 (seconds per line), stagger 0–0.5 (seconds between lines) |
the style's own |
Visitors who prefer reduced motion see the copy at once. The word cascade loads a small script only on pages whose hero uses it; without it, the title still appears after a second.
Platform Benefits¶
For Merchants¶
- Add features without developer time
- Test ideas quickly with low risk
- Seasonal campaigns made easy
- Improved conversion rates
For Developers¶
- Clean, maintainable architecture
- Reusable components
- Clear separation of concerns
- Well-documented APIs
For Customers¶
- Richer shopping experiences
- Faster page loads (lazy loading)
- Consistent cross-device experience
- Personalized content
Getting Started¶
Using Extensions¶
- Log into your admin panel
- Navigate to Extensions → Available Extensions
- Click Add Extension on any page, product, or collection
- Configure settings and save
- Preview your changes
- Publish when ready
Building Extensions¶
Ready to build your own extension? Check out our comprehensive developer guide:
Learn how to: - Create extension classes - Design templates for multiple themes - Handle configuration - Add JavaScript and CSS - Test extensions - Deploy to production
Support & Resources¶
- Developer Documentation:
/docs/developers/building-extensions.md - API Reference: JavaDoc available in codebase
- Example Extensions: Browse
commerce-core/src/main/java/uk/co/kedos/badger/settbuilder/extensions/ - Site-specific extensions: an extension written for one customer can be limited to that customer's site (see Site-Specific Extensions). Extensions are always our own code, shipped with the platform; there's no way to install third-party extension code.
Next Steps: - Browse the Built-In Extensions catalog - Read the Developer Guide - Explore the Christmas Mode Tutorial