HelperText

Small, subtle paragraph for persistent guidance under a form control — pair with an Input via aria-describedby.

stable
since v0.1.0
0.4 kB
forms
feedback

Preview

tsx

import { HelperText } from '@arshad-shah/cynosure-react';

export default function Example() {
  return <HelperText>Use at least 8 characters.</HelperText>;
}

Paired with an Input

Wire the helper to its input by giving the HelperText a stable id and pointing the input’s aria-describedby at it.

Preview

Open

tsx

import { HelperText, Input, Label, Stack } from '@arshad-shah/cynosure-react';
import { useId } from 'react';

export default function Example() {
  const inputId = useId();
  const helperId = useId();
  return (
    <Stack gap="2" style={{ width: 320 }}>
      <Label htmlFor={inputId}>Password</Label>
      <Input
        id={inputId}
        type="password"
        aria-describedby={helperId}
        placeholder="At least 8 characters"
      />
      <HelperText id={helperId}>
        Use at least 8 characters with a mix of letters and digits.
      </HelperText>
    </Stack>
  );
}

Inside FormField

Inside a FormField, prefer FormDescription — it renders a HelperText and auto-registers its id on the control via aria-describedby.

Preview

Open

tsx

import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormLabel,
  Input,
  Stack,
} from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Form>
      <Stack gap="4" style={{ width: 360 }}>
        <FormField name="username">
          <FormLabel>Username</FormLabel>
          <FormControl>
            <Input />
          </FormControl>
          <FormDescription>3 to 20 lowercase letters or digits.</FormDescription>
        </FormField>
      </Stack>
    </Form>
  );
}

API

PropTypeDefaultDescription

Accessibility

Renders a plain <p> — it carries no live-region semantics, which is the correct choice for persistent guidance.
Always associate it with the field via aria-describedby so the text is announced when focus enters the input.
Keep copy short and specific — long descriptions hurt readability for sighted and screen-reader users alike.
Use ErrorText (with role="alert") for transient validation; HelperText is for guidance that’s always true.

Recipes

Place directly under the input it describes — proximity matters as much as the aria wiring.
Within Form, swap HelperText for FormDescription so the wiring is automatic.
Reserve ErrorText for validation errors; keep HelperText for unconditional hints.