# Heading
## Кратко
`Heading` — семантический примитив заголовка. Он разделяет уровень заголовка и визуальный размер, чтобы структурой документа и типографической шкалой можно было управлять независимо.
## Импорт
```tsx
import { Heading, type HeadingAs, type HeadingProps, type HeadingSize } from '@vega-ui/react';
```
## Экспортируемые типы
- `HeadingProps`
- `HeadingAs = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'`
- `HeadingSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | number`
## Базовое использование
```tsx
import { Heading, Text } from '@vega-ui/react';
export default function BasicUsage() {
return (
Workspace settingsManage the name, members and billing of the Acme workspace.
);
}
```
## Варианты
- Уровень: от `h1` до `h6`
- Размер: визуальная шкала от `1` до `11`
- Насыщенность: `400`, `500`, `600`, `700`, `900`
## Пограничные случаи
- Визуальный размер и семантический уровень независимы.
- Крупные размеры заголовков всё равно наследуют токены межстрочного интервала заголовков, а не основного текста.
- `as` должен следовать структуре документа, а не только визуальному вкусу.
## Частые ошибки
- Выбор уровня заголовка по размеру вместо структуры документа.
- Использование `Heading` для подписей полей формы.
- Смешивание произвольных размеров шрифта со шкалой заголовков.
## Примеры
### Базовый
#### Базовый: структура документа
Сначала выбирайте `as` по структуре документа. Без `size` каждый уровень получает свой визуальный размер по умолчанию (`h1` → 11, `h2` → 10, `h3` → 8), поэтому обычной структуре дополнительные пропсы не нужны.
```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.
);
}
```
### Контролируемый/с состоянием
#### Контролируемый/с состоянием: счётчик в заголовке раздела
Заголовок показывает текущее число участников и подписывает `section` через `aria-labelledby`, поэтому имя региона обновляется вместе со списком. У каждой кнопки удаления имя с именем участника, а пустое состояние заменяет список.
```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.}
);
}
```
### Форма/интеграция
#### Форма/интеграция: заголовок, дающий имя форме
Форма получает доступное имя из `Heading` через `aria-labelledby` и становится именованным ориентиром. Группы внутри используют `FieldsetLegend`, а не новые заголовки, а отправка читает значения через `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 (
);
}
```
### Раскладка/оверлей
#### Раскладка/оверлей: иерархия внутри диалога
Заголовок диалога — `h2`, связанный через `aria-labelledby`, а его разделы используют `h3`, так что у диалога своя структура под страницей. Кнопка закрытия стоит в углу на логических отступах.
```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 (
);
}
```
### Ошибка
#### Ошибка: сводка ошибок с фокусом
При неудачной отправке над формой появляется сводка ошибок, и её `Heading` получает фокус через `tabIndex={-1}`, поэтому скринридер сразу озвучивает число проблем. Каждое сообщение ссылается на своё поле, а поля помечены `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 (
);
}
```
### Отключённый
#### Отключённый: заголовок раздела только для чтения
Раздел остаётся `h3` с прежним уровнем; приглушён только цвет. Элементы управления отключены через нативный `fieldset`, который подписан заголовком и описан заметкой с объяснением причины.
```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.
);
}
```
### Пограничный случай
#### Пограничный случай: маленький размер при верном уровне
Заголовки разделов боковой панели — `h2` в структуре, но с `size={2}`: `as` и `size` независимы, поэтому плотная раскладка не вынуждает выбирать неверный уровень.
```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 (
);
}
```
#### Пограничный случай: длинные заголовки в узкой колонке
`Heading` переносится как обычный текст. `textWrap: 'balance'` выравнивает строки длинного заголовка, а `overflowWrap: 'anywhere'` позволяет разорвать длинное составное слово, а не вылезти за колонку.
```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
);
}
```
#### Пограничный случай: уровень по глубине вложенности
Рекурсивный компонент вычисляет `as` из глубины и ограничивает его `h6`, потому что глубже уровней в HTML нет. Визуальный `size` уменьшается с глубиной отдельно от уровня.
```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 ;
}
```
## Анатомия
### Обзор
`Heading` — примитив из одной части. Корень отвечает за семантический уровень заголовка, визуальный размер и насыщенность шрифта.
### Обязательные части
#### `Heading`
Обязательная. Рендерит элемент заголовка и применяет типографику заголовков VegaUI.
### Необязательные части
Экспортируемых дочерних частей нет.
### Порядок композиции
1. `Heading`
2. содержимое заголовка
### Допустимые паттерны композиции
У заголовка есть `id`, и `section`, которую он озаглавливает, ссылается на него через `aria-labelledby`, поэтому регион получает то же имя, что и видимый заголовок.
```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.
);
}
```
### Недопустимые паттерны композиции
#### Уровень заголовка выбран только по визуальному размеру
Это ломает структуру документа.
#### Основной текст стилизован под структуру разделов
Это скрывает навигационную семантику от вспомогательных технологий.