Hero Banner Component User Guide
Category: Commerce & Merchandising
Palette Icon: Image Banner Icon (hero_banner)
Purpose: The Hero Banner is your page's primary high-impact headline block. It captures visitor attention with bold titles, background visuals, background animations, and primary/secondary call-to-action (CTA) buttons.
Every row in the palette carries a ? button that opens that component's own help: overview, mental model, when to use it versus the alternatives, a complete property reference, worked recipes, accessibility and translation notes, gotchas, troubleshooting and an FAQ. It ships with the build, so it can never drift from the component you are configuring.
This guide is the map — which block to reach for and how they combine. The ? is the manual for each one.
A page's page type decides which blocks it is offered. If a component named here is missing from your palette, the page type is why — not a missing permission. See Visual Builder mode.
This is what the ? opens. The Hero Banner's entry alone runs to fourteen
sections — Mental model, When to use vs alternatives, Page contexts where
it fits, Complete property reference, Common configurations (recipes),
Performance & file-size budgets, Accessibility checklist, Translation &
internationalization, Backwards compatibility, Gotchas, Troubleshooting,
FAQ and Pair with.
The header states the component's code (hero_banner), its category, and how
many configuration fields it exposes — 30+ for this one. That count is why
the field-by-field reference belongs in the product: it changes with the build.
1. Selecting a Banner Template
When you add a Hero Banner to your page, the first property control in the Inspector is the Template Selector:
Template Options Breakdown
| Template Option | Visual Layout | Ideal Use Case | Configurable Features |
|---|---|---|---|
| Classic | Left headline & CTAs, right image container. | E-commerce shop homepage, product category features. | Image height (Auto, Small, Medium, Large, Extra Large, Full), Image focus (Top, Center, Bottom). |
| Split | Two-column split layout with text card on one side. | Feature announcements, brand stories. | Image position (Left, Right), Image padding (None / Bleed, Small, Medium, Large). |
| Centered | Centered headline, subtitle, and primary/secondary CTAs over solid background. | Campaign landing pages, SaaS product headlines. | Solid background color token, background overlay animation. |
| Carousel | Multi-slide image carousel banner with slide navigation dots and arrows. | Storefront promotions, seasonal sales. | Slide list manager (Add Slide, Reorder Slides), per-slide image, title, and CTA links. |
| Video | Background video player with text overlay. | Brand video showcases, product demos. | Video URL (MP4 / Vimeo / YouTube), Poster image URL, Autoplay toggle, Loop toggle. |
| Premium | Dark canvas hero with stat highlight pills beneath CTAs. | High-converting SaaS, enterprise product features. | Stat pills list manager (e.g. "13 Modules", "3+ Gateways", "Tax-Ready"). |
2. Background Color Tokens & Animations
The Hero Banner supports theme-aware background styling that automatically adapts if your organization colors change:
A. Background Color Token Dropdown
| Dropdown Option | Live Color Effect | Purpose |
|---|---|---|
| Primary | Resolves to your Organization Primary Color (#2563eb). | Bold primary brand hero. |
| Secondary | Resolves to your Organization Secondary Color (#64748b). | Subtle secondary brand hero. |
| Accent | Resolves to your Organization Accent Color. | High-visibility promo banner. |
| Muted | Resolves to soft neutral background (#f8fafc). | Clean, light editorial hero. |
| Background | Resolves to main site background color (#ffffff). | Seamless transparent background. |
| Card | Resolves to card container background. | Floating card hero. |
B. Background Animated Layer Dropdown
Add dynamic visual effects behind your headline copy:
| Animation Option | Visual Effect | Best Used For |
|---|---|---|
| None | Static background color / image. | Clean, simple banners. |
| Aurora | Glowing, flowing northern-lights color waves. | Premium product launches. |
| Starfield | Twinkling star particle canvas. | Modern tech, SaaS, or dark mode sites. |
| Gradient Mesh | Smoothly morphing multi-color gradient background. | Creative agencies, design-focused brands. |
| Dot Grid | Subtle interactive grid of animated dots. | Software platforms, developer documentation. |
| Particles | Floating connected particle node network. | AI platforms, technology products. |
3. Configuring Call to Action (CTA) Buttons
Every Hero Banner template supports Primary and Secondary Call to Action buttons:
CTA Field Options
| Field Label | Control Type | Selectable Options | Purpose & Live Effect |
|---|---|---|---|
| Button Label | Text Input | Plain text (e.g., Shop New Arrivals) | Text displayed inside the CTA button. Supports multi-language translation. |
| Link Type | Dropdown Selector | • None • Project Page • Organization Page • External URL | Dictates where clicking the CTA button takes the visitor. |
| Select Project Page | Dropdown Selector | List of active project pages | Populates from your project's customer pages. |
| Select Org Page | Dropdown Selector | List of global org pages | Populates from organization defaults (e.g. Account, Terms). |
| External URL | Text Input | Full web URL (e.g. https://external.com) | Appears when Link Type = External URL. |
4. Entry Animation Dropdown
Control how the hero banner animates into view when a visitor opens your page:
- None: Appears instantly without animation.
- Fade: Smoothly fades in opacity.
- Slide Up: Slides upward into view.
- Slide Left: Slides in from the right edge.
- Scale: Scales smoothly from 95% to 100% size.
- Ken Burns: Subtle slow-zoom effect on the hero background image.