Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add section-header

Usage#

import {
  SectionHeader,
  SectionHeaderText,
  SectionHeaderHeading,
  SectionHeaderDescription,
  SectionHeaderActions,
} from "@/components/ui/section-header"
import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <SectionHeader>
      <SectionHeaderText>
        <Badge variant="success" dot pill>Best value</Badge>
        <SectionHeaderHeading>Discover our key features</SectionHeaderHeading>
        <SectionHeaderDescription>
          A unique set of essential features that distinguish us.
        </SectionHeaderDescription>
      </SectionHeaderText>
      <SectionHeaderActions>
        <Button>Get started</Button>
        <Button variant="outline">Explore features</Button>
      </SectionHeaderActions>
    </SectionHeader>
  )
}

Alignment#

align="left" (default) anchors the block to the leading edge; align="center" centers it in a capped column, the classic centered section lede.

Orientation#

orientation="stacked" (default) drops the actions below the text. split moves them beside the text on a row from the lg breakpoint up (and stacks again below it). Split is a left-aligned layout; centered headers always stack.

Sizes#

size scales the heading and description together to roughly the scale of a Heading 1 (lg), Heading 2 (md, the default), or Heading 3 (sm). It is independent of the heading level (the semantic tag), so an h2 can read at the Heading 1 size.

Values are mobile → sm (640px) → lg (1024px); the heading and description step up together at those breakpoints. Both slots inherit Tailwind's default type scale (no token override).

Responsive#

The header is responsive on every axis at once. size steps the heading and description up at sm and lg; the actions row stacks full-width on a phone (items-stretch) and returns to a wrapping row from sm; a split header lays the lede and actions side by side from lg and falls back to the stacked column below it; a centered block shrinks to the viewport instead of overflowing; and any inline SectionHeaderChip rides the heading (it is sized in em). Drag the frame, or use the mobile / tablet / desktop presets, to watch it recompose.

With an email capture#

The actions row composes any control, not just buttons: drop an Input beside a Button for a newsletter or waitlist lede. The row imposes one height on everything inside it, so the field and the button come out level without either of them being given a size.

Inline media#

Drop a SectionHeaderChip between the words of the heading to flow a mark or emoji inline with the copy. A framed chip (default) is a rounded tile that holds a logo, icon, or image, the app-icon look set right into the headline; a bare chip drops the box for a naked glyph or emoji interleaved with the text. It is sized entirely in em, so the tile, its radius, and the glyph inside all scale with the heading at every size and breakpoint. Chips are decorative by default (aria-hidden); pass an aria-label when one stands in for a word.

Drop the frame with variant="bare" and the chip is just a glyph or emoji sized to the cap height, so icons and emoji sit inline between the words without a container.

Reveal on scroll

Add reveal and the chip waits for the reader: until the heading scrolls into view it is closed, taking no width and giving back one of the two spaces around it, so the heading reads as plain copy. When it arrives, the words part to make room and the mark pops into the gap. It fires later than the library's other scroll gates, once the heading has climbed past the lower third of the screen: this animation is the thing you came to look at, so it waits until the heading is actually in front of you instead of playing while it is still a sliver at the bottom edge. Every gap in a heading opens together, so a heading wrapped over several lines keeps its line breaks the whole way; the marks then land one after another. Plays once, and with prefers-reduced-motion the chips are simply there. Scroll this preview out of view and reload to see it again.

Stagger#

A section can opt in to a load animation: set stagger and the lede cascades in on mount, each unit rising one beat after the last rather than the whole block appearing at once. It is off by default, so you choose where motion earns its keep. Pass stagger (or stagger={true}) for the default 70 ms cadence, or a number to set the gap between units yourself.

Two knobs shape how it reads. staggerBy picks the unit: "phrase" (default) reveals the lede part by part (eyebrow, heading, description, then the actions row); "word" reveals the heading and description word by word, so the copy types itself in. And staggerBlur adds a soft 4px → 0 focus pull as each unit lands, on top of the rise and fade. Try the combinations:

// Off by default: the header just renders.
<SectionHeader>…</SectionHeader>

// Opt in: cascade the parts at the DS's 70ms cadence.
<SectionHeader stagger>…</SectionHeader>

// Reveal the copy word by word, with a soft focus pull.
<SectionHeader stagger staggerBy="word" staggerBlur>…</SectionHeader>

// Tune the gap between units (snappier or more relaxed).
<SectionHeader stagger={40} staggerBy="word">…</SectionHeader>

// Below the fold? Play as the reader reaches it, not on load.
<SectionHeader stagger staggerTrigger="inView">…</SectionHeader>

By default the cascade plays on mount, the right gate for an above-the-fold load reveal. For a section further down the page, set staggerTrigger="inView" and it waits until the header scrolls into view, so the reveal happens as the reader arrives instead of finishing off-screen. (The demo above uses inView, which is why it replays each time you scroll back to it.)

The whole cascade is continuous: in word mode the eyebrow leads, the heading and description words flow in reading order, and the actions land last, one slot after the final word. It plays once and honors prefers-reduced-motion (every unit simply appears). It is backed by the same motion tokens as the Stagger primitive, so a header reads identically to a staggered list or grid below it. For the content below the header (a feature grid, a list of cards), wrap it in the Stagger primitive (which takes the matching blur and inView props) to keep one cascade down the section.

API reference#

FAQ#