# Heading
## Summary
`Heading` is the semantic heading primitive. It separates heading level from visual size so document structure and typography scale can be managed independently.
## Imports
```tsx
import { Heading, type HeadingAs, type HeadingProps, type HeadingSize } from '@vega-ui/react';
```
## Exported Types
- `HeadingProps`
- `HeadingAs = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'`
- `HeadingSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | number`
## Basic Usage
```tsx
import { Heading, Text } from '@vega-ui/react';
export default function BasicUsage() {
return (
Workspace settingsManage the name, members and billing of the Acme workspace.
);
}
```
## Variants
- Level: `h1` through `h6`
- Size: visual scale `1` through `11`
- Weight: `400`, `500`, `600`, `700`, `900`
## Edge Cases
- Visual size and semantic level are independent.
- Large heading sizes still inherit heading line-height tokens rather than body line-height tokens.
- `as` should follow document outline, not visual taste alone.
## Common Mistakes
- Picking heading level by size instead of document structure.
- Using `Heading` for form labels.
- Mixing arbitrary custom font sizes with the heading scale.
## Examples
### Basic
#### Basic: document outline
Choose `as` from the outline first. Without `size`, each level gets its default visual size (`h1` → 11, `h2` → 10, `h3` → 8), so a plain outline needs no extra props.
```tsx
import { Heading, Text } from '@vega-ui/react';
export default function DocumentOutline() {
return (
Getting startedSet up your workspace in three steps.
Invite your teamMembers get access to every public project.
Roles and permissionsAdmins manage billing; editors can create projects.
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: count in a section heading
The heading shows the current member count and labels the `section` through `aria-labelledby`, so the region name updates with the list. Each remove button gets a name that includes the member, and the empty state replaces the list.
```tsx
import { Button, Heading, Text } from '@vega-ui/react';
import { useState } from 'react';
const candidates = ['Alicia Gómez', 'Ben Carter', 'Chen Wei', 'Dana Novak', 'Emeka Obi'];
export default function HeadingWithDynamicCount() {
const [members, setMembers] = useState(candidates.slice(0, 2));
const nextCandidate = candidates.find((name) => !members.includes(name));
const addMember = () => {
if (nextCandidate === undefined) return;
setMembers([...members, nextCandidate]);
};
return (
Members ({members.length})
{members.map((name) => (
{name}
))}
{members.length === 0 && No members yet.}
);
}
```
### Form/Integration
#### Form/Integration: heading that names a form
The form takes its accessible name from the `Heading` through `aria-labelledby`, which makes it a named form landmark. Groups inside use `FieldsetLegend`, not more headings, and the submit reads the values with `FormData`.
```tsx
import {
Button,
Fieldset,
FieldsetLegend,
Heading,
Label,
Text,
TextField,
TextFieldInput,
} from '@vega-ui/react';
import { useState, type FormEvent } from 'react';
export default function FieldsetSectionTitle() {
const [saved, setSaved] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setSaved(`Invoices for ${data.get('company')} go to ${data.get('billingEmail')}.`);
};
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: hierarchy inside a dialog
The dialog title is an `h2` linked with `aria-labelledby`, and its sections use `h3`, so the dialog has its own outline under the page. The close button sits in the corner with logical insets.
```tsx
import {
Button,
Dialog,
DialogClose,
DialogContent,
DialogTrigger,
Heading,
Icon,
IconButton,
Text,
} from '@vega-ui/react';
import { XIcon } from '@vega-ui/icons';
import type { CSSProperties } from 'react';
export default function DialogTitleHierarchy() {
return (
);
}
```
### Error
#### Error: focused error summary
On a failed submit an error summary appears above the form and its `Heading` receives focus through `tabIndex={-1}`, so screen readers announce the problem count right away. Each message links to its field, and the fields are marked with `aria-invalid`.
```tsx
import { Button, Heading, Label, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { useEffect, useRef, useState, type CSSProperties, type FormEvent } from 'react';
interface FieldError {
id: string
message: string
}
export default function ErrorSummaryHeading() {
const summaryHeading = useRef(null);
const [errors, setErrors] = useState([]);
const [attempt, setAttempt] = useState(0);
const [sent, setSent] = useState(false);
useEffect(() => {
if (attempt === 0) return;
summaryHeading.current?.focus();
}, [attempt]);
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
const nextErrors: FieldError[] = [];
if (String(data.get('name')).trim() === '') {
nextErrors.push({ id: 'contact-name', message: 'Enter your name' });
}
if (!String(data.get('email')).includes('@')) {
nextErrors.push({ id: 'contact-email', message: 'Enter an email address like name@example.com' });
}
setErrors(nextErrors);
setSent(nextErrors.length === 0);
if (nextErrors.length > 0) setAttempt(attempt + 1);
};
const hasError = (id: string) => errors.some((error) => error.id === id);
return (
);
}
```
### Disabled
#### Disabled: heading of a read-only section
The section stays an `h3` with its level intact; only the color is muted. The controls are disabled through a native `fieldset`, which is labelled by the heading and described by the note that explains why.
```tsx
import { Button, Heading, Label, Text, TextField, TextFieldInput } from '@vega-ui/react';
import type { CSSProperties } from 'react';
export default function MutedConfigurationHeading() {
return (
Legacy webhooks
Read-only since the v2 API. Move your endpoints to Event subscriptions.
);
}
```
### Edge
#### Edge: small visual size, correct level
Sidebar section titles are `h2` in the outline but use `size={2}`: `as` and `size` are independent, so a dense layout does not force a wrong level.
```tsx
import { Heading, Text } from '@vega-ui/react';
const sections = [
{ title: 'Recent activity', items: ['Invoice #4821 paid', 'Dana joined the workspace'] },
{ title: 'Pinned projects', items: ['Website redesign', 'Mobile onboarding'] },
];
export default function VisualSizeSmallerThanSemanticLevel() {
return (
);
}
```
#### Edge: long titles in a narrow column
`Heading` wraps like normal text. `textWrap: 'balance'` evens out the lines of a long title, and `overflowWrap: 'anywhere'` lets a long compound word break instead of overflowing the column.
```tsx
import { Heading } from '@vega-ui/react';
export default function LongHeadingWrap() {
return (
Quarterly revenue report for the Europe, Middle East and Africa region
Datenschutzgrundverordnungskonformität
);
}
```
#### Edge: level from nesting depth
A recursive component computes `as` from its depth and clamps it at `h6`, because HTML has no deeper level. The visual `size` shrinks with depth separately from the level.
```tsx
import { Heading, Text, type HeadingAs } from '@vega-ui/react';
interface Topic {
title: string
children?: Topic[]
}
const guide: Topic = {
title: 'Admin guide',
children: [
{
title: 'Security',
children: [
{
title: 'Single sign-on',
children: [
{
title: 'SAML setup',
children: [
{
title: 'Okta',
children: [
{ title: 'Group mapping', children: [{ title: 'Nested groups' }] },
],
},
],
},
],
},
],
},
{ title: 'Billing' },
],
};
const levels: HeadingAs[] = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
function TopicSection({ topic, depth }: { topic: Topic, depth: number }) {
const level = levels[Math.min(depth, levels.length - 1)];
return (
{topic.title}
{depth >= levels.length && Deeper than h6, shown at the h6 level}
{topic.children?.map((child) => (
))}
);
}
export default function NestedHeadingLevels() {
return ;
}
```
## Anatomy
### Overview
`Heading` is a single-part primitive. The root owns semantic heading level, visual size, and weight.
### Required Parts
#### `Heading`
Required. Renders the heading element and applies VegaUI heading typography.
### Optional Parts
There are no exported child parts.
### Composition Order
1. `Heading`
2. heading content
### Valid Composition Patterns
The heading carries an `id`, and the `section` it titles references it with `aria-labelledby`, so the region gets the same name as the visible title.
```tsx
import { Heading, Text } from '@vega-ui/react';
export default function ValidCompositionPatterns() {
return (
Billing contactsInvoices are sent to finance@acme.io and the workspace owner.
);
}
```
### Invalid Composition Patterns
#### Heading level chosen only for visual size
This breaks document structure.
#### Body text styled to mimic section structure
This hides navigational semantics from assistive technology.