HelperText

Patterns

Inline Field Guidance

When to use:

• a field needs one short clarification

Composition notes:

• keep the copy below the field
• keep the message actionable

Trade-offs:

• improves completion
• adds vertical density to forms

import { HelperText, Label, TextField, TextFieldInput } from '@vega-ui/react';
import { useId } from 'react';

export default function FieldHint() {
  const id = useId();
  const hintId = `${id}-hint`;

  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-3)', width: '100%' }}>
      <Label htmlFor={id}>Recovery email</Label>
      <TextField>
        <TextFieldInput id={id} type='email' autoComplete='email' aria-describedby={hintId} />

Local Validation Message

When to use:

• the error belongs to one field

Composition notes:

• set invalid state on the field as well
• keep the error copy specific

Trade-offs:

• fast to scan
• should not replace broader form error summaries when several fields fail

import { Button, HelperText, Label, TextField, TextFieldInput } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';

const getMessage = (input: HTMLInputElement) => {
  if (input.validity.valueMissing) return 'Enter a postal code.';
  if (input.validity.patternMismatch) return 'Use 5 digits, for example 10115.';
  return '';
};

export default function NativeValidityMessage() {
  const id = useId();
  const [error, setError] = useState('');

Group Hint

When to use:

• several related controls need one short instruction

Composition notes:

• place the helper text close to the group label
• avoid repeating the same message for every child control

Trade-offs:

• reduces duplication
• can be missed if visually disconnected from the group

import {
  Button,
  Checkbox,
  CheckboxCheckedIcon,
  CheckboxIndicator,
  CheckboxInput,
  Fieldset,
  FieldsetLegend,
  HelperText,
  Text,
} from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';

Comparison

Quick Decision Rule

Use HelperText for short supporting copy near a field. Use Text for general copy and Label for the field name itself.

HelperText vs Text

Use HelperText when:

• the copy is field-adjacent guidance

Use Text when:

• the copy is ordinary body content

HelperText vs Label

Use HelperText when:

• the copy is supplemental guidance

Use Label when:

• the text is the primary visible field label

HelperText vs validation banners

Use HelperText when:

• the guidance or error is local to one field or one grouped control

Use a larger alert or summary pattern when:

• the error is form-wide or cross-field

Choose This Component When

• copy belongs directly to one control or control group
• the tone should stay secondary or validation-adjacent
• the content should remain visually subordinate to the label and input

Do Not Choose This Component When

• the copy is the main label
• the content is long-form explanation

Troubleshooting

The Field Still Feels Unlabeled

Symptom

There is supporting copy, but users still cannot tell what the field is for.

Likely Cause

HelperText was used without a clear visible label.

How To Verify

• hide the helper copy mentally
• check whether one obvious label still remains

Fix

Add Label or FieldsetLegend for the primary field name.

Error Copy Shows But The Field Does Not Look Invalid

Symptom

The text communicates an error, but the control itself remains visually normal.

Likely Cause

Only HelperText error was set.

How To Verify

• inspect the field props
• confirm whether the field wrapper or input has its invalid state applied

Fix

Apply the error state to the field and keep HelperText as supporting copy.

Helper Text Is Too Long To Scan

Symptom

Users ignore the message because it reads like a paragraph.

Likely Cause

The component is being used for explanatory content instead of concise guidance.

How To Verify

• count the message length
• check whether the copy still fits a quick form-scanning flow

Fix

Move longer explanations into Text, help content, or a separate explanatory section.