Skip to content
Browse documentation
whisk/ui

Heading

Create a semantic heading with an independent visual style.

Overview

Heading renders a native document heading while letting its visual size follow the surrounding interface.

Use when

Text introduces a document section or subsection.

Use instead

Use Text with visual emphasis when the text is not part of the document outline.

Usage

Workspace settings

import { Heading } from "@smoothie-framework/whisk-react";

<Heading level={2}>Workspace settings</Heading>

Examples

Sizes

Use size to change the visual treatment without changing the heading level.

Heading (sm)

Heading (md)

Heading (lg)

Heading (xl)

Heading (2xl)

Heading (3xl)

Heading (4xl)

Heading (5xl)

Heading (6xl)

import { Heading, Stack } from "@smoothie-framework/whisk-react";

<Stack gap={2}>
  <Heading level={3} size="sm">Heading (sm)</Heading>
  <Heading level={3} size="md">Heading (md)</Heading>
  <Heading level={3} size="lg">Heading (lg)</Heading>
  <Heading level={3} size="xl">Heading (xl)</Heading>
  <Heading level={3} size="2xl">Heading (2xl)</Heading>
  <Heading level={3} size="3xl">Heading (3xl)</Heading>
  <Heading level={3} size="4xl">Heading (4xl)</Heading>
  <Heading level={3} size="5xl">Heading (5xl)</Heading>
  <Heading level={3} size="6xl">Heading (6xl)</Heading>
</Stack>

Highlight

Use a native mark inside a heading to emphasize matching words without changing the heading's semantics. Mark is native HTML, not a Whisk-themed component.

Build agent interfaces on one design system

import { Heading } from "@smoothie-framework/whisk-react";

<Heading level={2} size="2xl">
  Build <mark>agent interfaces</mark> on one design system
</Heading>

Level

Use level to choose the native h1 through h6 element from the document outline. When size is omitted, each level uses its default visual size.

Level 2

Level 3

Level 4

import { Heading, Stack } from "@smoothie-framework/whisk-react";

<Stack gap={2}>
  <Heading level={2}>Level 2</Heading>
  <Heading level={3}>Level 3</Heading>
  <Heading level={4}>Level 4</Heading>
</Stack>

Weights

Use weight for visual emphasis while preserving the heading level.

Normal

Medium

Semibold

Bold

import { Heading, Stack } from "@smoothie-framework/whisk-react";

<Stack gap={2}>
  <Heading level={3} weight="normal">Normal</Heading>
  <Heading level={3} weight="medium">Medium</Heading>
  <Heading level={3} weight="semibold">Semibold</Heading>
  <Heading level={3} weight="bold">Bold</Heading>
</Stack>

Section link

Give a linked section heading an id. tabIndex={-1} makes it focusable from code after navigation without adding it to the normal Tab sequence.

Go to notifications

Notifications

import { Heading, Link, Stack } from "@smoothie-framework/whisk-react";

<Stack gap={2}>
  <Link href="#notifications">Go to notifications</Link>
  <Heading id="notifications" level={2} tabIndex={-1}>
    Notifications
  </Heading>
</Stack>

Composition

Use Heading with other primitives to establish the primary label for a contained interface section.

Ship your first agent

Connect a model, add tools, and deploy from one workspace.

import { Box, Button, Heading, Stack, Text } from "@smoothie-framework/whisk-react";

<Box padding={4} background="surface2" rounded="md">
  <Stack gap={3} align="start">
    <Heading level={2} size="xl">Ship your first agent</Heading>
    <Text color="subtle">Connect a model, add tools, and deploy from one workspace.</Text>
    <Button>Start building</Button>
  </Stack>
</Box>

Props

Component props

PropTypeDefaultDescription
level1 | 2 | 3 | 4 | 5 | 62Select the native h1 through h6 element. This sets the document outline, not only the appearance.
size2xs | xs | sm | md | lg | xl | 2xl | 3xl | 4xl | 5xl | 6xl | 7xl | 8xl | 9xlh1: 4xl | h2: 3xl | h3: 2xl | h4: xl | h5: lg | h6: mdOverride the level-based visual size without changing the native heading level.
weightthin | light | normal | medium | semibold | bold | extraboldboldAdjust visual emphasis while preserving the heading level.
alignleft | center | right | justifyleftAlign the heading's inline text without changing its outline level.
colordefault | subtle | disabled | inverse | accent | error | success | warning | stringdefaultUse the shown semantic names first. Values such as text-subtle are raw theme color tokens, not semantic aliases; pass them as strings and declare static values in utilityUses.
uppercasetrue | falsefalseTransform the visual text to uppercase without changing its accessible name.
textStyleUtilityValuenoneApply a configured typography treatment when the theme owns the complete style.

Shared props

PropSupportedNotes
as / asChildNoThe required heading level owns the h1–h6 host.
Style propsYesUse the shared static style-prop surface. See Style props.
className / styleYesApplied to the heading host.
refYesForwards to the heading host.
Native HTML attributesYesNative heading attributes are forwarded.

Accessibility

Set level from the document outline, then change size only for visual design. Do not skip levels just to get a smaller heading. Do not use Heading for text that is not a real section title, and do not rely on size, color, or uppercase to communicate hierarchy. Each page normally has one h1; use native id and tabIndex={-1} when a heading should be focusable from code after following a section link.