Hero
Full-width page-top block that sits directly below the site header. Renders with different sizes and styling based on the type prop, default for homepages/landing pages and featured for editorial pages. The type sets the padding and the title size; every slot renders under every type, so an editorial page keeps its breadcrumb and imagery. The offset position value pushes the hero down to clear a sticky site header, and --hero-offset-margin-top sets how far. Used on every page that has a visual page-top treatment - homepages, landing pages, interior content pages, and blog listings.
Usage
When to use
- At the top of every page that needs a visible page-top treatment
- Homepages and landing pages - the big, full-featured default type
- Blog listings and editorial narrative pages -
featuredtype, which tightens the padding and the title without dropping any slot
When not to use
- On pages that rely on a bare breadcrumb plus heading (use the breadcrumb plus a plain
h1inside content) - For marketing promo bars or site-wide alerts - use the announcement component
- For in-content feature highlights - use a section or callout
Do
- Use exactly one hero per page
- Ensure the
<h1>inside the hero is the only<h1>on the page - Pick the type from the page's own content field, not from page-context detection
- Add the
offsetposition value when the header is sticky, and set--hero-offset-margin-topto match the header height
Don't
- Autoplay videos or parallax effects by default
- Stack multiple heroes on a single page
- Wrap the hero in additional containers - it is full-bleed
API
Slots
| Slot | Required | Description |
|---|---|---|
title | Yes | Main heading text. Required; the hero does not render when empty. |
supertitle | - | Small label rendered above the title. |
breadcrumb | - | Pre-rendered breadcrumb HTML. |
content | - | Body slot rendered under the title. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
background_image | object | - | Image object with url and alt keys. Rendered as an absolutely positioned layer behind the content. |
featured_image | object | - | Image object with url and alt keys. Rendered side-by-side with the content in a split layout. |
background_blend | string | - | CSS mix-blend-mode value for the background image. |
title_id | string | - | ID for the title element, referenced by aria-labelledby. Defaults to a generated value when omitted. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.fluid | Layout | - | Full-width, no max-width. |
.contained | Layout | Yes | Constrained to a max-width. |
.offset | Position | - | Shifts the component clear of the fixed or sticky chrome above it. |
.default | Type | Yes | Hero type: default for homepages, featured for editorial pages. |
.featured | Type | - | Hero type: default for homepages, featured for editorial pages. |
Examples
Default
Big, full-featured homepage/landing hero with supertitle, breadcrumb, background image, and featured image.
Featured
Editorial variant - tighter padding and a smaller title, still carrying the breadcrumb and supertitle the page supplies.
With background image
Default hero with a background image and configurable blend mode.
With featured image
Split layout with text on the left and a featured image on the right.
With offset
Hero using .hero.offset to clear a sticky header. The gap comes from --hero-offset-margin-top.
Accessibility
- WCAG 2.2 AA
- Title must always be a real
<h1>- only one<h1>per page. - Supertitle is a
<p>or<span>, visually smaller but not a heading - does not nest inside the<h1>. - Hero root must be a skip-link target.
- Background image is decorative by default; if meaningful, it must expose a description via
role="img"andaria-label. - Featured image must have meaningful alt text or empty alt if decorative.
- Breadcrumb inside the hero follows the breadcrumb component's own ARIA (
<nav aria-label="Breadcrumb">). - Contrast between text and background image must meet AA.
prefers-reduced-motionmust disable parallax, reveal, and autoplay effects.
Dependencies
- breadcrumb - rendered inside the hero
- container - the
containedlayout value takes its maximum width - header - sits above the hero; the
offsetposition value clears a sticky one - icon - may appear in supertitle or content slots
Related
- breadcrumb - rendered inside the hero
- header - sits above the hero