Heading

Pro

A heading whose level is the page's outline and whose size is only how it looks, so a small heading deep in a card can still be an <h2>. level is required: a screen reader's list of headings is the page's table of contents, and a level guessed from a size gets it wrong. It reads no HeadingScope (5.0.0): the level you give is the one drawn, so a heading you place by hand never moves.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2 and 4.1.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/heading

Brings in: heading-level, text, tokens, utils · npm: @base-ui/react@^1.9.0

Usage

TSX · The example above

"use client"

import { Heading } from "@/components/candor/heading"
import { Text } from "@/components/candor/text"

// The level is the page's outline; the size is only how it looks.
export default function Example() {
  return (
    <div className="flex max-w-md flex-col gap-3">
      <Heading level={2} size="xl">
        Agent settings
      </Heading>
      <Heading level={3} size="sm" tone="muted">
        Permissions
      </Heading>
      <Text size="sm">The agent can read the CRM and draft emails. Sending needs your approval.</Text>
    </div>
  )
}

<Heading>

Prop	Type	Default	Description
levelrequired	`HeadingLevel`	—	The heading's level in the outline, which picks the element (`2` draws an `<h2>`). Required.
size	`HeadingSize \| undefined`	—	How large it looks. Left out, the level sets it: `3xl` for a level 1 down to `sm` for a level 6.
tone	`TextTone \| undefined`	—	The colour, by what the heading is. Inherited when left out.
render	`useRender.RenderProp \| undefined`	—	The element to draw instead of the level's `<h1>` to `<h6>`. One that isn't the level's heading element is given `role="heading"` and `aria-level`, so the outline stays true; a function that returns the level's element isn't.
className	`string \| undefined`	—	Classes for the element, applied last, so they win over the props.
children	`React.ReactNode \| undefined`	—	The heading's words.

Also takes the props of Omit<React.ComponentProps<"h2">, "color">.

Values

headingSizes

The size each level draws at when size is left out.

Record<HeadingLevel, HeadingSize>

Types

HeadingSize: How large a heading looks, a step of the type scale, separate from where it sits in the outline.; "xs" | "sm" | "base" | "lg" | "xl" | "2xl" | "3xl" | "4xl"

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

HeadingLevel from @/lib/candor/heading-level: A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.; 1 | 2 | 3 | 4 | 5 | 6