HeroesCopy Anchor Link

Heroes are introductory sections that establish the visual identity of a page.

Puzzle Pieces provides a flexible Hero component and a collection of specialized presets. All presets share the same underlying implementation, making them easy to customize without maintaining separate layouts.

InstallationCopy Anchor Link

Import the Hero components from Puzzle Pieces:

import {
  Hero,
  SplitHero,
  CenteredHero,
  FullScreenHero,
  ImageHero,
  VideoHero,
} from "@puzzle-ui/pieces";

ComponentsCopy Anchor Link

Basic usageCopy Anchor Link

Use Hero for complete control over the layout and content.

LayoutsCopy Anchor Link

The Hero component supports four layout configurations.

SplitCopy Anchor Link

Text and media are displayed in separate columns.

CenteredCopy Anchor Link

Content is centered horizontally.

Full widthCopy Anchor Link

The inner container uses the full available width.

AsymmetricCopy Anchor Link

The media and content columns use different proportions.

Media positioningCopy Anchor Link

Control where media is displayed using mediaPosition.

Background media can also be supplied directly.

HeightCopy Anchor Link

Control the minimum height of the hero.

ThemesCopy Anchor Link

Hero supports four theme configurations.

Hero consumes semantic Puzzle Theme tokens for its background, foreground, typography and spacing.

OverlaysCopy Anchor Link

Overlays improve text readability when using background media.

ContentCopy Anchor Link

Hero supports several content slots.

EyebrowCopy Anchor Link

A short introductory label above the heading.

DescriptionCopy Anchor Link

Additional introductory text.

ActionsCopy Anchor Link

Use existing Puzzle UI components for buttons and other actions.

SearchCopy Anchor Link

The search slot can contain any existing Puzzle form components.

MetaCopy Anchor Link

Use meta for supplementary information such as availability, opening hours or product details.

ChildrenCopy Anchor Link

Additional content can be placed between the description and the action slots.

Responsive behaviorCopy Anchor Link

Hero automatically adapts its layout to smaller screens.

• Split layouts become single-column layouts.
• Asymmetric layouts become single-column layouts.
• Media can move before content on mobile.
• Typography uses responsive sizing.
• Horizontal and vertical spacing adapt to available screen space.

Use reverseOnMobile to control the order of content and media.

Disable reversal when the content should remain before the media.

Specialized presetsCopy Anchor Link

Presets provide sensible defaults for common website types.

All presets inherit the properties of Hero and can be customized.

SplitHeroCopy Anchor Link

CenteredHeroCopy Anchor Link

FullScreenHeroCopy Anchor Link

VideoHeroCopy Anchor Link

Background videos are muted, loop automatically and respect the user's reduced-motion preference.

ImageHeroCopy Anchor Link

MinimalHeroCopy Anchor Link

EditorialHeroCopy Anchor Link

AgencyHeroCopy Anchor Link

ProductHeroCopy Anchor Link

SaaSHeroCopy Anchor Link

StoreHeroCopy Anchor Link

RestaurantHeroCopy Anchor Link

AccommodationHeroCopy Anchor Link

PrintShopHeroCopy Anchor Link

DashboardWelcomeHeroCopy Anchor Link

AppHeroCopy Anchor Link

CampaignHeroCopy Anchor Link

ComingSoonHeroCopy Anchor Link

SearchHeroCopy Anchor Link

CustomizationCopy Anchor Link

All presets inherit the full Hero API.

For example, an AccommodationHero can use a split layout instead of its default background layout.

CSS customizationCopy Anchor Link

Hero uses regular CSS and semantic Puzzle Theme tokens.

The root element has the puzzle-hero class.

You can customize its appearance through CSS variables.

.custom-hero {
  --puzzle-hero-padding-inline: var(--puzzle-space-8);
  --puzzle-hero-padding-block: var(--puzzle-space-16);
  --puzzle-hero-gap: var(--puzzle-space-10);
  --puzzle-hero-background: var(--puzzle-color-surface);
  --puzzle-hero-foreground: var(--puzzle-color-text);
}

You can also target individual elements using their class names.

AccessibilityCopy Anchor Link

Hero is designed to work with assistive technologies.

• Uses semantic section elements by default.
• Supports custom semantic elements through the as property.
• Supports configurable heading levels through titleAs.
• Supports accessible labels.
• Decorative background images have empty alternative text.
• Background videos are hidden from assistive technology.
• Background videos respect prefers-reduced-motion.
• Interactive content remains accessible through its original Puzzle components.

Always provide meaningful alternative text for informative images.

Use one primary heading per page where appropriate.

API referenceCopy Anchor Link

Hero propertiesCopy Anchor Link

HeroLayoutCopy Anchor Link

type HeroLayout = "centered" | "split" | "full-width" | "asymmetric";

HeroMediaPositionCopy Anchor Link

type HeroMediaPosition = "left" | "right" | "background";

HeroAlignmentCopy Anchor Link

type HeroAlignment = "start" | "center" | "end";

HeroHeightCopy Anchor Link

type HeroHeight = "auto" | "large" | "viewport";

HeroThemeCopy Anchor Link

type HeroTheme = "light" | "dark" | "contrast" | "brand";

HeroOverlayCopy Anchor Link

type HeroOverlay = "none" | "subtle" | "strong" | "gradient";

HeroContentWidthCopy Anchor Link

type HeroContentWidth = "narrow" | "normal" | "wide" | "full";

HeroVideoSourceCopy Anchor Link

type HeroVideoSource = {
  src: string;
  type?: string;
  poster?: string;
};