Skip to main content

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 - featured type, 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 h1 inside 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 offset position value when the header is sticky, and set --hero-offset-margin-top to 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​

SlotRequiredDescription
titleYesMain 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​

PropTypeDefaultDescription
background_imageobject-Image object with url and alt keys. Rendered as an absolutely positioned layer behind the content.
featured_imageobject-Image object with url and alt keys. Rendered side-by-side with the content in a split layout.
background_blendstring-CSS mix-blend-mode value for the background image.
title_idstring-ID for the title element, referenced by aria-labelledby. Defaults to a generated value when omitted.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.fluidLayout-Full-width, no max-width.
.containedLayoutYesConstrained to a max-width.
.offsetPosition-Shifts the component clear of the fixed or sticky chrome above it.
.defaultTypeYesHero type: default for homepages, featured for editorial pages.
.featuredType-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.

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.

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" and aria-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-motion must disable parallax, reveal, and autoplay effects.

Dependencies​

  • breadcrumb - rendered inside the hero
  • container - the contained layout value takes its maximum width
  • header - sits above the hero; the offset position value clears a sticky one
  • icon - may appear in supertitle or content slots