Skip to main content
In progress

FormElementLabel

A FormElementLabel is a text component used to label form elements like inputs, textareas, and select fields. It provides accessible labeling and visual hierarchy for form fields, ensuring clear associations between labels and their corresponding form controls.

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

<FormElementLabel label="Email address" isRequired />

Why to use​

FormElementLabel ensures proper semantic HTML and accessibility standards for form labels. Using this component provides:

  • Accessibility: Properly associates labels with form inputs through the for attribute, improving usability for screen reader users
  • Consistency: Provides a unified styling and behavior across all form labels in Yle applications
  • Flexibility: Supports visual indicators for required fields, optional fields, disabled states, and visually-hidden labels for specific use cases
  • Built-in spacing: Manages margin and spacing automatically, reducing the need for custom CSS

When to use​

Use FormElementLabel when you need a visible, accessible label for a single form control.

Do
  • Custom form elements that need to align with YDS form components
Don't
  • Don't use for content that isn't label element — for headings that group multiple fields (eg. Radios and Checkboxes), use FormGroupLabel instead
  • Don't use FormElementLabel for YDS form components – use the form component's label and labelOptions props instead

Writing Guidelines​

Do
  • Write labels in active voice and from the user's perspective (e.g., "Your email address" instead of "Email address to be entered")
  • Use simple, familiar words that users understand without needing to look up definitions
  • Keep labels concise but descriptive enough to be useful
  • Use sentence case for consistency (capitalize the first word only)
  • Include units of measurement in labels when relevant (e.g., "Weight (kg)")
  • Be specific about what information is expected (e.g., "Phone number (with country code)")
Don't
  • Don't use all caps or excessive punctuation in labels
  • Don't repeat words from the placeholder text in your label
  • Don't use abbreviations unless they're universally understood
  • Don't make labels overly long - break into multiple labels if needed
  • Don't use ambiguous or vague wording like "Enter information" or "Add details"

Key FormElementLabel Props​

Use these props to configure the FormElementLabel component.

label​

The main text content displayed for the label. This is the primary text that describes the associated form element.

TypeExampleDescription
stringText displayed in the label
Code example
<FormElementLabel label="Full name" />
<FormElementLabel label="Email address" />

isRequired​

Indicates whether the associated form field is required. When true, the label is typically styled to show it's mandatory.

TypeExampleDescription
booleanMarks the field as required
Code example
<FormElementLabel label="Email" isRequired />
<FormElementLabel label="Optional note" isRequired={false} />

optionalLabel​

Additional text displayed alongside the main label to indicate optional fields. Only shows when isRequired is false.

TypeExampleDescription
stringText indicating optional field
Code example
<FormElementLabel label="Phone" optionalLabel="(optional)" />
<FormElementLabel label="Website" optionalLabel="(not required)" />

isDisabled​

Disables the label visually, typically used when the associated form field is disabled.

TypeExampleDescription
booleanDisplays label in disabled state
Code example
<FormElementLabel label="Archived field" isDisabled />
<FormElementLabel label="Active field" isDisabled={false} />

isHidden​

Hides the label visually while keeping it accessible to screen readers (using the visually-hidden class).

TypeExampleDescription
booleanHides label from visual display
Code example
<FormElementLabel label="Search query" isHidden />
<FormElementLabel label="Username" isHidden={false} />

hasMarginBottom​

Controls whether the label includes bottom margin spacing. Enabled by default to provide spacing from the associated form element.

TypeExampleDescription
booleanAdds bottom margin to the label
Code example
<FormElementLabel label="Name" hasMarginBottom={true} />
<FormElementLabel label="Name" hasMarginBottom={false} />

Behavior​

  • The label is always associated with the input and appears above or beside it.
  • The label text displays with standard styling by default.
  • When isRequired is false, optionalLabel is displayed alongside the main label.
  • When optionalLabel is provided, it displays alongside the main label for optional fields (when isRequired is false).
  • Disabled labels appear with reduced styling when the associated input is disabled.
  • Visually-hidden labels remain accessible to screen readers while not displaying on the page.
  • Bottom margin is applied by default to create spacing from the associated input.
  • The label can be associated with form controls using the htmlFor attribute or by wrapping the control.

Accessibility​

  • The label uses semantic <label> HTML elements to properly associate with form inputs.
  • Labels must always be present or programmatically associated with form controls.
  • Screen readers announce labels clearly, providing context for form navigation.
    (WCAG 3.3.2 — Labels or Instructions)
  • Optional fields are described appropriately to users.
  • Visually-hidden labels maintain full accessibility for screen reader users.

API Reference​

Props​

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

PropTypeRequiredDefaultDescription
labelstringNo''The main text content displayed for the label
optionalLabelstringNo—Additional text to indicate optional fields (only shows when isRequired is false)
isRequiredbooleanNofalseIndicates whether the associated form field is required
isDisabledbooleanNofalseDisables the label visually when the form field is disabled
isHiddenbooleanNofalseHides the label visually while keeping it accessible to screen readers
hasMarginBottombooleanNotrueControls whether the label includes bottom margin spacing

Type Definitions​

export interface FormElementLabelDSProps {
  label?: string;
  optionalLabel?: string;
  isRequired?: boolean;
  isDisabled?: boolean;
  isHidden?: boolean;
  hasMarginBottom?: boolean;
}

export type FormElementLabelProps = React.LabelHTMLAttributes<HTMLLabelElement> &
  FormElementLabelDSProps;