# HelperText Guides

## 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

```tsx
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} />
      </TextField>
      <HelperText id={hintId}>Used only if you lose access to your main inbox.</HelperText>
    </div>
  );
}
```

### 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

```tsx
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('');
  const invalid = error !== '';

  const onInvalid = (event: FormEvent<HTMLInputElement>) => {
    event.preventDefault();
    setError(getMessage(event.currentTarget));
  };

  const onInput = (event: FormEvent<HTMLInputElement>) => {
    if (!invalid) return;
    setError(getMessage(event.currentTarget));
  };

  return (
    <form onSubmit={(event) => event.preventDefault()} style={{ display: 'grid', gap: 'var(--spacing-12)', width: '100%' }}>
      <div style={{ display: 'grid', gap: 'var(--spacing-3)' }}>
        <Label htmlFor={id}>Postal code</Label>
        <TextField error={invalid}>
          <TextFieldInput
            id={id}
            name='postalCode'
            inputMode='numeric'
            autoComplete='postal-code'
            required
            pattern='\d{5}'
            aria-invalid={invalid}
            aria-describedby={invalid ? `${id}-error ${id}-hint` : `${id}-hint`}
            onInvalid={onInvalid}
            onInput={onInput}
          />
        </TextField>
        {invalid && <HelperText id={`${id}-error`} error>{error}</HelperText>}
        <HelperText id={`${id}-hint`}>We deliver within Germany only.</HelperText>
      </div>
      <Button type='submit' style={{ justifySelf: 'start' }}>Check delivery</Button>
    </form>
  );
}
```

### 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

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

const CHANNELS = ['Email', 'Slack', 'SMS'];

export default function GroupHint() {
  const id = useId();
  const [saved, setSaved] = useState('');

  const onSubmit = (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    const channels = new FormData(event.currentTarget).getAll('channels');
    setSaved(channels.length === 0 ? 'Alerts turned off' : `Alerts via ${channels.join(', ')}`);
  };

  return (
    <form onSubmit={onSubmit} style={{ display: 'grid', gap: 'var(--spacing-12)', width: '100%' }}>
      <Fieldset aria-describedby={`${id}-hint`}>
        <FieldsetLegend>Incident alerts</FieldsetLegend>
        <HelperText id={`${id}-hint`}>We send each alert to every channel you pick.</HelperText>
        {CHANNELS.map((channel) => (
          <Checkbox key={channel} style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-4)' }}>
            <CheckboxInput name='channels' value={channel} defaultChecked={channel === 'Email'} />
            <CheckboxIndicator>
              <CheckboxCheckedIcon />
            </CheckboxIndicator>
            {channel}
          </Checkbox>
        ))}
      </Fieldset>
      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-6)' }}>
        <Button type='submit'>Save</Button>
        <Text size={2} role='status' style={{ color: 'var(--label-secondary)' }}>{saved}</Text>
      </div>
    </form>
  );
}
```

## 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.