Text

Patterns

Helper Copy Below A Field

When to use:

• a field needs short explanatory text

Composition notes:

• keep helper copy secondary in tone
• place it close to the associated field

Trade-offs:

• improves clarity
• adds vertical density

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<HTMLFormElement>) => {
    event.preventDefault();
    const data = new FormData(event.currentTarget);

Status Copy

When to use:

• a UI surface needs concise state text

Composition notes:

• keep the copy short
• choose color based on state semantics

Trade-offs:

• fast to scan
• color-only meaning should still be avoided

import { Button, Text } from '@vega-ui/react';
import { useEffect, useState, type CSSProperties } from 'react';

const relative = new Intl.RelativeTimeFormat('en-US', { numeric: 'auto' });

export default function StatusCopy() {
  const [lastSync, setLastSync] = useState(() => Date.now() - 4 * 60 * 1000);
  const [now, setNow] = useState(() => Date.now());

  useEffect(() => {
    const timer = window.setInterval(() => setNow(Date.now()), 15000);
    return () => window.clearInterval(timer);

Multiline Descriptive Copy

When to use:

• the content contains intentional newline breaks

Composition notes:

• Text uses white-space: pre-line
• keep line breaks meaningful rather than decorative

Trade-offs:

• preserves authored copy structure
• unexpected newlines in data will also be rendered

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 (
    <div style={{ display: 'grid', gap: 'var(--spacing-8)', width: '100%' }}>
      <Text size={3}>{address}</Text>
      <Text size={3} style={{ whiteSpace: 'normal' }}>{description}</Text>
    </div>
  );

Comparison

Quick Decision Rule

Use Text for body copy, helper text, and descriptive content. Use Heading, Label, or Code when the content has a more specific semantic role.

Text vs Heading

• Use Text for paragraphs and supporting copy.
• Use Heading for document structure.

Text vs Label

• Use Text for general copy.
• Use Label when the text names a form control.

Text vs Code

• Use Text for prose.
• Use Code for inline code, tokens, commands, or identifiers.

Choose This Component When

• you need body typography from the shared scale
• semantic meaning comes from surrounding layout or the rendered child

Do Not Choose This Component When

• the content is a heading
• the content is a form label
• the content should read as inline code

Troubleshooting

The Copy Looks Like A Heading But Is Not Announced As One

Symptom

Large text appears visually like a section title, but assistive technology does not treat it as a heading.

Likely Cause

Text was used where Heading should have been used.

How To Verify

• inspect the rendered element
• confirm it is not an h1 through h6

Fix

Use Heading when the content participates in document structure.

Newlines Are Rendering Unexpectedly

Symptom

Line breaks appear in the UI even though the text was expected to render as one paragraph.

Likely Cause

Text uses white-space: pre-line, so newline characters are preserved.

How To Verify

• inspect the source string
• check for \n or multiline content

Fix

Normalize the content before rendering or use a different rendering strategy when line breaks are not intended.

Text Color Overrides Make Helper Copy Hard To Read

Symptom

Secondary or custom-styled text has insufficient contrast.

Likely Cause

Low-contrast overrides were applied through inline styles or custom variables.

How To Verify

• compare the rendered color against the background
• check whether primary and secondary text still read distinctly

Fix

Prefer semantic theme tokens and retest contrast when overriding --t-color.