# Text
## Кратко
`Text` — базовый примитив основной типографики. Он управляет размером и начертанием и допускает семантическую композицию через `asChild`.
## Импорты
```tsx
import { Text, type TextProps, type TextSize } from '@vega-ui/react';
```
## Экспортируемые типы
- `TextProps`
- `TextSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11`
## Базовое использование
```tsx
import { Text } from '@vega-ui/react';
export default function BasicUsage() {
return (
Your trial ends in 5 days. Add a payment method to keep your projects, history and integrations.
);
}
```
## Варианты
- Размер: от `1` до `11`
- Начертание: `400`, `500`, `600`, `700`, `900`
- Композиция: элемент по умолчанию или `asChild`
## Пограничные случаи
- `asChild` меняет отрендеренный элемент, но сохраняет контракт стилей текста.
- `white-space: pre-line` сохраняет переносы строк из строк содержимого.
- Очень крупные размеры текста всё равно нужно проверять на раскладке и длине строки.
## Частые ошибки
- Использовать `Text` там, где заголовки документа должны быть семантическими `Heading`.
- Переопределять начертание и размер вручную вместо дизайн-шкалы.
- Забывать, что в многострочном содержимом сохраняются переносы строк.
## Примеры
### Базовый
#### Базовый: текст статьи
По умолчанию `Text` рендерит ``; абзацы используют `asChild` с `
`, чтобы сохранить семантику абзаца. Вложенный `Text` с `fontWeight` выделяет фрагмент, а подпись автора приглушена через `--t-color`.
```tsx
import { Heading, Text } from '@vega-ui/react';
import type { CSSProperties } from 'react';
export default function BodyCopy() {
return (
Scheduled maintenance on March 18
Posted by the Platform team
We are upgrading the primary database cluster. The dashboard stays available, but exports and
webhooks are paused for up to 30 minutes starting at 02:00 UTC.
Queued webhooks are delivered automatically once the upgrade finishes. No action is needed.
);
}
```
### Контролируемый/с состоянием
#### Контролируемый/с состоянием: текст из состояния
Фраза вычисляется из числа мест через `Intl.PluralRules` и на нуле сменяется другим сообщением. `aria-live='polite'` озвучивает изменение после каждого клика, не перемещая фокус.
```tsx
import { Button, Text } from '@vega-ui/react';
import { useState } from 'react';
const totalSeats = 5;
const plural = new Intl.PluralRules('en-US');
export default function DynamicHelperCopy() {
const [assigned, setAssigned] = useState(3);
const remaining = totalSeats - assigned;
const seatWord = plural.select(remaining) === 'one' ? 'seat' : 'seats';
return (
{remaining === 0 ? 'All seats are taken. Upgrade to invite more people.' : `${remaining} ${seatWord} left on the Team plan.`}
);
}
```
### Форма/интеграция
#### Форма/интеграция: подсказка и счётчик символов
И подсказка, и живой счётчик — элементы `Text`, на которые поле ссылается через `aria-describedby`, поэтому скринридер читает их вместе с полем. Значение отправляется через `FormData`, а сброс очищает счётчик вместе с полем.
```tsx
import { Button, Label, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { useState, type CSSProperties, type FormEvent } from 'react';
const maxLength = 40;
export default function HelperTextBelowAField() {
const [headline, setHeadline] = useState('');
const [saved, setSaved] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setSaved(`Saved headline: ${data.get('headline')}`);
};
const onReset = () => {
setHeadline('');
setSaved('');
};
return (
);
}
```
### Раскладка/оверлей
#### Раскладка/оверлей: описание в диалоге
Диалог получает доступное имя из заголовка, а описание — из абзаца `Text` через `aria-labelledby` и `aria-describedby`, поэтому скринридер сообщает о последствиях сразу при открытии.
```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 DescriptiveCopyInADialog() {
return (
);
}
```
### Ошибка
#### Ошибка: встроенное сообщение валидации
Купон проверяется при отправке. Неизвестный код показывает сообщение `Text` цветом ошибки, связывает его через `aria-describedby` и выставляет `aria-invalid`; правка поля снимает ошибку. Цвет — не единственный сигнал: само сообщение объясняет, что не так.
```tsx
import { Button, Label, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { useState, type CSSProperties, type FormEvent } from 'react';
const validCodes = ['SPRING20', 'WELCOME10'];
export default function InlineValidationCopy() {
const [error, setError] = useState('');
const [applied, setApplied] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
const code = String(data.get('coupon')).trim().toUpperCase();
if (!validCodes.includes(code)) {
setApplied('');
setError(`${code === '' ? 'This code' : code} is not valid or has expired.`);
return;
}
setError('');
setApplied(`${code} applied to your order.`);
};
return (
);
}
```
### Отключённый
#### Отключённый: пояснение к отключённому разделу
Весь `Fieldset` отключён, а приглушённый `Text` объясняет почему. Пояснение связано с группой через `aria-describedby`: отключённые элементы не получают фокус, и заметку рядом легко пропустить.
```tsx
import { Button, Fieldset, FieldsetLegend, Label, Text, TextField, TextFieldInput } from '@vega-ui/react';
import type { CSSProperties } from 'react';
export default function MutedExplanatoryText() {
return (
Scheduled exports are available on the Business plan.
);
}
```
### Пограничный случай
#### Пограничный случай: переводы строк в данных
`Text` использует `white-space: pre-line`: переводы строк в строке становятся разрывами, что удобно для адреса. Текст из CMS с жёсткими переносами отрисуется так же, поэтому переопределяйте это через `whiteSpace: 'normal'`, когда переводы строк не несут смысла.
```tsx
import { Text } from '@vega-ui/react';
const address = 'Acme GmbH\nTorstraße 140\n10119 Berlin\nGermany';
const description = 'Soft merino wool sweater with a relaxed fit,\nribbed cuffs and a crew neck.\nMachine washable at 30\u00a0°C.';
export default function MultilineContent() {
return (
{address}{description}
);
}
```
#### Пограничный случай: длинный текст в узкой колонке
Для обрезки нужен блочный бокс: `Text` — строчный ``, поэтому `textOverflow: 'ellipsis'` работает только вместе с `display: 'block'`, `overflow: 'hidden'` и `whiteSpace: 'nowrap'`; `title` оставляет полное имя доступным. Длинные строки без пробелов, например адреса почты, переносятся через `overflowWrap: 'anywhere'`.
```tsx
import { Text } from '@vega-ui/react';
const files = [
'Q1-2026-board-presentation-final-v7-approved-by-legal.pdf',
'customer-interviews-transcripts-berlin-and-lisbon.docx',
'logo.svg',
];
export default function LongTextOverflow() {
return (
{files.map((file) => (
{file}
))}
Invoices are sent to accounts-payable.emea-region@northwind-traders.example.com
);
}
```
#### Пограничный случай: имена справа налево внутри фразы
Имена на иврите или арабском внутри английской фразы могут переставить соседние числа и знаки препинания. Обёртка имени в `` через `asChild` изолирует его направление.
```tsx
import { Text } from '@vega-ui/react';
const comments = [
{ author: 'Maya Cohen', handle: 'מאיה כהן', count: 3 },
{ author: 'Omar Haddad', handle: 'عمر حداد', count: 12 },
];
export default function BidiUserContent() {
return (
{comments.map((comment) => (
{comment.handle}
{' '}
left {comment.count} comments
))}
);
}
```
## Анатомия
### Обзор
`Text` — типографский примитив из одной части. Корень владеет всем публичным контрактом размера, начертания и семантической композиции основного текста.
### Обязательные части
#### `Text`
Обязательна. Рендерит текстовый узел со стилями основной типографики VegaUI.
### Необязательные части
Экспортируемых дочерних частей нет.
### Порядок композиции
1. `Text`
2. содержимое или целевой элемент `asChild`
### Допустимые варианты композиции
Внешний `Text` рендерит `
` через `asChild`; строчные `Text` внутри остаются `` или рендерят семантические элементы вроде `