Skip to content

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

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

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

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

  1. Browse Extensions Visit the extension library in your admin panel

  2. Configure Settings Use the visual editor to customize behavior

  3. Place Extensions Drag and drop extensions into page slots

  4. Preview & Publish See changes before customers do

  5. Monitor Performance Track engagement and conversion impact

For Developers

  1. Create Extension Class Extend base classes with your logic

  2. Design Templates Build Thymeleaf templates for rendering

  3. Add Resources Include CSS/JS for interactivity

  4. Register Extension Spring Boot auto-discovers your extension

  5. 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

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.

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 around and Never wrap force either behaviour.
  • Maximum Number of Products — set to 0 to 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:

  1. pageSize on a collectionProductGrid placed on the collection itself
  2. the collection's pageSizeOverride configuration property
  3. pageSize on the stereotype's collectionProductGrid
  4. the site's defaultCollectionPaginationPagesSize config (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.

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.

{"preset": "gradient", "height": "compact", "backgroundImage": "...", "slots": {...}}

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.

{"preset": "gradient", "contentAlign": "container", "backgroundImage": "...", "slots": {...}}

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-accent and --color-on-dark-accent at 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: reduce it 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
{"preset": "minimal", "entrance": "rise", "entranceTuning": {"stagger": 0.2}, "slots": {...}}

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

  1. Log into your admin panel
  2. Navigate to Extensions → Available Extensions
  3. Click Add Extension on any page, product, or collection
  4. Configure settings and save
  5. Preview your changes
  6. Publish when ready

Building Extensions

Ready to build your own extension? Check out our comprehensive developer guide:

📘 Building Extensions 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