Skip to content

Heading

Semantic heading with decoupled level and visual size so document outline and typography scale independently.

stable
since v0.1.0
4.41 kB
typography
primitive

Preview

tsx

import { Heading } from '@arshad-shah/cynosure-react';

export default function Example() {
  return <Heading level={1}>Welcome to Cynosure</Heading>;
}

Levels

Use level to set the rendered tag (1–6). When size is omitted the visual scale defaults to the matching heading composite token, so a level={2} heading looks like an h2 out of the box.

Preview

tsx

import { Heading } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
      <Heading level={1}>Heading level 1</Heading>
      <Heading level={2}>Heading level 2</Heading>
      <Heading level={3}>Heading level 3</Heading>
      <Heading level={4}>Heading level 4</Heading>
      <Heading level={5}>Heading level 5</Heading>
      <Heading level={6}>Heading level 6</Heading>
    </div>
  );
}

Sizes

Nine sizes are exposed — xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl. Pair a small size with a high level to keep semantics intact while shrinking the type scale, or vice versa.

Preview

tsx

import { Heading } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
      <Heading level={2} size="5xl">
        Size 5xl
      </Heading>
      <Heading level={2} size="4xl">
        Size 4xl
      </Heading>
      <Heading level={2} size="3xl">
        Size 3xl
      </Heading>
      <Heading level={2} size="2xl">
        Size 2xl
      </Heading>
      <Heading level={2} size="xl">
        Size xl
      </Heading>
      <Heading level={2} size="lg">
        Size lg
      </Heading>
      <Heading level={2} size="md">
        Size md
      </Heading>
      <Heading level={2} size="sm">
        Size sm
      </Heading>
      <Heading level={2} size="xs">
        Size xs
      </Heading>
    </div>
  );
}

Weights

Override the default weight from the heading token with regular, medium, semibold, or bold.

Preview

tsx

import { Heading } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.25rem' }}>
      <Heading level={3} weight="regular">
        Regular weight
      </Heading>
      <Heading level={3} weight="medium">
        Medium weight
      </Heading>
      <Heading level={3} weight="semibold">
        Semibold weight
      </Heading>
      <Heading level={3} weight="bold">
        Bold weight
      </Heading>
    </div>
  );
}

Truncate

Pass truncate for ellipsis on one line or a number for multi-line clamp — handy for card titles inside fixed layouts.

Preview

tsx

import { Heading } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', maxWidth: '20rem' }}>
      <Heading level={3} truncate>
        A long card title that elides when the row runs out of room
      </Heading>
      <Heading level={3} size="lg" truncate={2}>
        Two-line clamp keeps the title scannable while still showing enough of the longer phrasing
        to make sense
      </Heading>
    </div>
  );
}

API

PropTypeDefaultDescription

level

1|2|3|4|5|6

2

Semantic heading level — renders `h1`..`h6` for document outline / SEO. Use this to fix the structural level; pair with `size` to tune visuals.

size

Responsive<HeadingSize>

—

Visual type-scale step. Decoupled from `level` so visual hierarchy can diverge from semantic hierarchy. Falls back to the level-matched token.

weight

Responsive<HeadingWeight>

—

Override the level's default font weight.

align

Responsive<HeadingAlign>

—

Horizontal text alignment.

truncate

number|boolean

—

`true` → single-line truncation; `number > 1` → multi-line line-clamp.

className

string

—

Additional class names appended after Cynosure's base classes.

style

CSSProperties

—

Inline style overrides merged last.

children

ReactNode

—

Heading text content.

padding

Responsive<SpaceToken>

—

Padding on all four sides. Token from the spacing scale.

paddingX

Responsive<SpaceToken>

—

Horizontal padding (left + right). Overrides `padding` on the X axis.

paddingY

Responsive<SpaceToken>

—

Vertical padding (top + bottom). Overrides `padding` on the Y axis.

paddingTop

Responsive<SpaceToken>

—

Padding on the top edge. Beats `padding` / `paddingY`.

paddingRight

Responsive<SpaceToken>

—

Padding on the right (inline-end in RTL) edge.

paddingBottom

Responsive<SpaceToken>

—

Padding on the bottom edge.

paddingLeft

Responsive<SpaceToken>

—

Padding on the left (inline-start in RTL) edge.

margin

Responsive<MarginValue>

—

Margin on all four sides. Accepts the spacing scale or `"auto"`.

marginX

Responsive<MarginValue>

—

Horizontal margin (left + right). Use `"auto"` to centre.

marginY

Responsive<MarginValue>

—

Vertical margin (top + bottom).

marginTop

Responsive<MarginValue>

—

Margin on the top edge.

marginRight

Responsive<MarginValue>

—

Margin on the right edge.

marginBottom

Responsive<MarginValue>

—

Margin on the bottom edge.

marginLeft

Responsive<MarginValue>

—

Margin on the left edge.

width

Responsive<SizeValue>

—

Element width. Accepts a `SpaceToken`, `LengthValue`, or named alias.

height

Responsive<SizeValue>

—

Element height. Accepts a `SpaceToken`, `LengthValue`, or named alias.

minWidth

Responsive<SizeValue>

—

Minimum width — useful for preventing flex children from collapsing.

maxWidth

Responsive<SizeValue>

—

Maximum width — `"prose"` caps to a comfortable reading measure.

minHeight

Responsive<SizeValue>

—

Minimum height.

maxHeight

Responsive<SizeValue>

—

Maximum height.

background

Responsive<ColorToken>

—

Background colour. Use a `ColorToken` like `"bg.surface"` for theme awareness.

color

Responsive<ColorToken>

—

Text colour. Inherits unless set.

borderColor

Responsive<ColorToken>

—

Border colour. Pair with `borderWidth` to make the border visible.

borderWidth

Responsive<BorderWidth>

—

Border thickness in scale steps.

borderStyle

Responsive<BorderStyle>

—

Border line style.

borderRadius

Responsive<RadiusToken>

—

Corner rounding token.

boxShadow

Responsive<ShadowToken>

—

Drop-shadow token from the elevation scale.

opacity

Responsive<number | `${number}`>

—

Opacity 0–1. Use sparingly — prefer surface tokens over translucency.

overflow

Responsive<Overflow>

—

How content that exceeds the box is handled.

overflowX

Responsive<Overflow>

—

Horizontal-axis overflow control. Overrides `overflow` for the X axis.

overflowY

Responsive<Overflow>

—

Vertical-axis overflow control.

display

Responsive<Display>

—

CSS `display` value. `"contents"` removes the element's box from layout.

position

Responsive<Position>

—

CSS `position`. Pair with `top`/`right`/`bottom`/`left` for placement.

top

Responsive<InsetValue>

—

Top inset (when positioned). Accepts a `SpaceToken`, `"auto"`, `"0"`, or `LengthValue`.

right

Responsive<InsetValue>

—

Right inset (when positioned).

bottom

Responsive<InsetValue>

—

Bottom inset (when positioned).

left

Responsive<InsetValue>

—

Left inset (when positioned).

zIndex

Responsive<ZIndexToken>

—

Stacking-context layer token (`"modal"`, `"tooltip"`, …).

gridColumn

Responsive<string>

—

Grid-column shorthand (e.g. `"1 / 3"`, `"span 2"`).

gridRow

Responsive<string>

—

Grid-row shorthand.

gridArea

Responsive<string>

—

Named grid area.

flex

Responsive<"1" | "none" | "auto" | "initial" | (string & {})>

—

Shorthand: `1 | auto | none | initial | <css>`. Resolves to `flex` on the child.

flexGrow

Responsive<number | `${number}`>

—

Grow factor inside a flex container.

flexShrink

Responsive<number | `${number}`>

—

Shrink factor inside a flex container.

flexBasis

Responsive<"content" | SizeValue>

—

Initial main-axis size before grow/shrink.

alignSelf

Responsive<AlignSelf>

—

Override `align-items` for a single child.

justifySelf

Responsive<JustifySelf>

—

Override `justify-items` for a single child (grid).

order

Responsive<number | `${number}`>

—

Flex/grid child reorder index.

asChild

boolean

—

When `true`, renders the primitive's single React child via `Slot`, forwarding className/style/ref/event handlers onto it.

Accessibility

level always controls the rendered element so the document outline stays correct for screen readers and SEO.
Decouple size from level to keep visual hierarchy flexible without skipping headings (don’t jump from h1 to h4 just to shrink type).
One h1 per page; reach for level={2} or deeper inside sections.
truncate hides overflow visually only — keep the full heading in the DOM so assistive tech receives it.
Maintain enough contrast between heading colour and background; large weights still need to pass WCAG large-text minimums.

Recipes

Pair Heading with Text variant="lead" directly underneath for a familiar title + lede pattern.
Use align="center" for hero headings and align="start" (default) for body sections.
Combine a small Text variant="overline" above a Heading for a section eyebrow without losing semantics.
Use asChild to project Heading typography onto a link wrapper for clickable card titles.