Skip to main content
In progress

FormGroupLabel

A FormGroupLabel is a semantic label component used to label groups of related form elements, such as radio buttons, checkboxes, or other fieldsets. It serves as the legend for grouped form controls, providing clear context and improving accessibility and user understanding.

Contact preference
Code example
import { FormGroupLabel } from '@yleisradio/yds-components-react';

<FormGroupLabel label="Contact preference" isRequired />

Why to use​

FormGroupLabel ensures proper semantic HTML and accessibility for grouped form elements. Using this component provides:

  • Accessibility: Uses the semantic <legend> element to properly associate labels with grouped form controls
  • Semantic HTML: Follows HTML standards for fieldset legends, improving document structure
  • Screen reader support: Screen readers announce the legend to users, providing context for form groups
  • Consistency: Ensures visual and behavioral consistency across all grouped form labels in Yle applications
  • Flexibility: Supports required and optional indicators, hidden labels, and additional content

When to use​

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

Do
  • Custom grouped form elements that need to align with YDS form components
Don't
  • Don't use for content that is a label element — for headings that are assigned to single fields (eg. Text inputs and Selects), use FormElementLabel instead
  • Don't use FormGroupLabel for YDS form components – use the form component's label and labelOptions props instead

Writing Guidelines​

Do
  • Write group labels from the user's perspective (e.g., "How would you like to be contacted?" instead of "Contact method selection")
  • Use simple, clear language that describes the choice or grouping
  • Keep labels concise but descriptive enough to be useful
  • Use sentence case for consistency
  • Be specific about what you're asking (e.g., "Which subscription level interests you?")
Don't
  • Don't use all caps or excessive punctuation
  • Don't make labels overly long - consider breaking into multiple groups if needed
  • Don't use ambiguous wording like "Choose options" without clarifying context
  • Don't use technical jargon that users won't understand

Key FormGroupLabel Props​

Use these props to configure the FormGroupLabel component.

label​

The main text content displayed for the group label. This describes the purpose of the grouped form elements.

TypeExampleDescription
stringContact preferenceText displayed in the group label
Code example
<FormGroupLabel label="Contact preference" />
<FormGroupLabel label="Billing frequency" />

isRequired​

Indicates whether the grouped form controls require a selection. When true, the label is typically styled to show it's mandatory.

TypeExampleDescription
booleanContact preferenceMarks the group as required
Code example
<FormGroupLabel label="Contact preference" isRequired />
<FormGroupLabel label="Additional options" isRequired={false} />

optionalLabel​

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

TypeExampleDescription
stringPreferences (optional)Text indicating optional group
Code example
<FormGroupLabel label="Additional preferences" optionalLabel="(optional)" />
<FormGroupLabel label="Extra options" optionalLabel="(not required)" />

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
<FormGroupLabel label="Select category" isHidden />
<FormGroupLabel label="Choose option" isHidden={false} />

Behavior​

  • The label is rendered as a <legend> element within a <fieldset> for semantic HTML
  • The legend is associated with all grouped form controls within the fieldset
  • Visual styling indicates required/optional status through indicators

Accessibility​

  • Screen readers announce the legend before reading individual form controls in the group
  • Screen readers announce the legend to provide context for the grouped controls

API Reference​

Props​

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

PropTypeRequiredDefaultDescription
labelstringNo''The main text content displayed for the group label
optionalLabelstringNo—Additional text to indicate optional groups (only shows when isRequired is false)
isRequiredbooleanNofalseIndicates whether the grouped form controls require a selection
isHiddenbooleanNofalseHides the label visually while keeping it accessible to screen readers

Type Definitions​

export interface FormGroupLabelDSProps {
  label?: string;
  optionalLabel?: string;
  isRequired?: boolean;
  isHidden?: boolean;
}

export type FormGroupLabelProps = React.HTMLAttributes<HTMLLegendElement> & FormGroupLabelDSProps;