Skip to main content

FormElementDescription

A FormElementDescription is a text component used to provide additional help text, guidance, or clarifications below form labels and inputs. It helps users understand what information is expected or required for a specific field, improving form usability and reducing errors.

This field accepts email addresses in the format: name@example.com

Code example
import { FormElementDescription } from '@yleisradio/yds-components-react';

<FormElementDescription text="This field accepts email addresses in the format: name@example.com" />

Why to use​

FormElementDescription enhances form clarity and user guidance. Using this component provides:

  • User guidance: Provides contextual help and clarification about what input is expected
  • Error prevention: Clear instructions reduce user mistakes and form abandonment
  • Accessibility: Works with form labels and inputs to create a complete accessible form experience

When to use​

Use the FormElementDescription component only when you're building a custom form (e.g. native inputs with FormElementLabel) and need help text below a field. For YDS form components (TextInput, Select, TextArea, etc.), use their label and description props instead of this component.

Do
  • Format requirements (e.g. date, phone) or input constraints (length, characters)
  • A short example of valid input or optional-field hint
Don't
  • Don't use with YDS form components — use the form component's label and description props instead
  • Don't use as the field label — use FormElementLabel or the form component's label prop
  • Don't use for validation errors — use the form element's error state or error prop
  • Don't put critical or required info only in the description — keep it in the label or visible UI

Writing Guidelines​

Do
  • Write in a conversational, helpful tone
  • Use concrete examples when describing formats or requirements
  • Keep descriptions short and concise
Don't
  • Don't use overly technical language or jargon
  • Don't write in all caps or use excessive punctuation
  • Don't make descriptions longer than one or two sentences
  • Don't use descriptions to explain why a field is required (use the isRequired prop on FormElementLabel instead)

Key FormElementDescription Props​

Use these props to configure the FormElementDescription component.

text​

The descriptive text content displayed below the form input. This provides helpful guidance or clarification.

TypeExampleDescription
string

Format: DD.MM.YYYY

Help text displayed in the description
Code example
<FormElementDescription text="Format: DD.MM.YYYY" />
<FormElementDescription text="Must be at least 8 characters long" />
<FormElementDescription text="Example: john.doe@example.com" />

Behavior​

  • The description text is displayed as a paragraph element below the form input
  • The component is always visible (no hidden states)
  • Text styling is consistent across all form descriptions for visual hierarchy
  • The description is associated with its form control through proximity and context

Accessibility​

  • The description should be associated with its form input using the id attribute and aria-describedby
  • Help text is available to screen reader users and provides important context
  • The component uses semantic HTML (<p> element) for proper document structure

API Reference​

Props​

The FormElementDescription component accepts all standard HTML <p> attributes in addition to the following props:

PropTypeRequiredDefaultDescription
textstringNo''The descriptive help text to display

Type Definitions​

export interface FormElementDescriptionProps
  extends React.LabelHTMLAttributes<HTMLParagraphElement> {
  text?: string;
}