Skip to Content

React Section Header Component

Compose a section eyebrow, heading, description, and action group with responsive alignment and theme-aware typography.

Use SectionHeader to compose the introductory content shared by page sections. It uses the UI package's Heading and Text primitives, inherits colors from its parent section, and omits the header entirely when all slots are empty.

Beta API maturity: Beta. This shared API will be exercised by upcoming Pieces section families before its shape is considered stable.

Import

import { Section, SectionHeader } from "@puzzle-ui/ui";

Basic usage

Use Section for the section root and SectionHeader for its introductory content. Pass controls and framework-specific links through actions; the header does not own navigation or application state.

390 × 844

Alignment and heading semantics

alignment controls the header's content alignment. It does not change the DOM order. Choose titleAs to match the page's heading hierarchy; titleLevel controls visual typography independently.

390 × 844

Use alignment="end" for a right-aligned introduction. Action items wrap when they do not fit on one line. The component uses CSS and does not measure the viewport or require a container query.

API

PropTypeDefaultDescription
eyebrowReactNode—Optional short label above the heading.
titleReactNode—Optional section heading. When omitted, no heading is rendered.
titleAsElementType"h2"Semantic element used for the title.
titleIdstring—ID for associating the title with the enclosing section's aria-labelledby.
titleLevelHeadingLevel"headline2"Theme typography role, independent of the heading element.
descriptionReactNode—Optional supporting content.
actionsReactNode—Optional consumer-provided links, buttons, or other controls.
alignment"start" | "center" | "end""start"Alignment for content and the action group.
classNamestring—Additional class on the semantic <header>.
styleCSSProperties—Inline styles for the header root.
id, role, aria-*, data-*Native <header> attributes—Native attributes are forwarded to the root element.

SectionHeader does not accept arbitrary children; use its named content slots. If all slots are absent or empty, it returns null. Numeric content such as title={0} remains renderable.

Theme and responsive behavior

The header uses Heading and Text from @puzzle-ui/ui and inherits its foreground color from the surrounding section. Spacing and content width use Theme CSS variables (--puzzle-space-3 and --puzzle-content-width). Use Section for themed backgrounds and content width, and Container, Grid, or Stack for surrounding layout; do not add another section/container wrapper around this component.

Accessibility and rendering

  • Keep the heading level in the document hierarchy; changing titleAs does not automatically change the visual titleLevel.
  • Connect the enclosing section with aria-labelledby={titleId} when the heading should name that section.
  • Pass native buttons, links, or UI controls in actions; ensure each has an accessible name and visible focus.
  • The component renders no browser APIs or effects and can produce server markup. Verify framework and hydration behavior in the target application.
  • There is no animation, so no reduced-motion override is necessary.