Label

Labels identify form inputs and provide optional description text and contextual help.

Component

Use fd-label to label form inputs with a native <label> element, optional required indicator, description/hint text, and an InfoTip disclosure button for supplementary contextual help.

When to use

• Labeling standalone form inputs — text inputs, selects, textareas, date pickers, and file inputs that are not inside a group component.
• A field needs hint text — description text explains format, constraints, or purpose without cluttering the label.
• Supplementary contextual help — use the InfoTip when definitions or "why we ask" explanations are useful but would overwhelm if always visible.

When not to use

• Don't use for grouped inputs — fd-radio-group and fd-checkbox-group have their own built-in legend and description slots.
• Don't hide critical instructions in the InfoTip — if users need the information to complete the field correctly, make it always-visible hint text.
• Don't use without a for attribute — every fd-label should point to the id of its associated input.

Examples

Label variants — basic, required with description, with InfoTip, and full-featured. Open Storybook for interactive controls. View in Storybook →

Properties

Name	Type	Default	Description
for	string | undefined	undefined	Target control ID. Required for real native label association.
label	string	``	Visible label text
required	boolean	false	Adds the required indicator and screen-reader-only required text
description	string | undefined	undefined	Always-visible hint text rendered below the label
infotip	string | undefined	undefined	Supplementary plain-text help shown in the InfoTip panel
infotip-label	string | undefined	undefined	Accessible name override for the InfoTip trigger. Defaults to More information about [label].

Best practices

Do

Write self-explanatory labels in plain language

Labels should use everyday words. Avoid internal jargon or abbreviations without context.

Don't

Use vague or abbreviated labels

Labels like "ID" or "No." force users to guess what information is expected.

Do

Use hint text for format requirements

Always-visible hint text like "Format: XXX-XX-XXXX" prevents errors before submission.

Don't

Hide format requirements in the InfoTip

If users need the information to fill in the field correctly, it should be visible without an extra click.

Do

Use InfoTip for supplementary definitions

Regulatory terms, eligibility criteria, or "why we ask" explanations are good InfoTip content.

Don't

Use InfoTip for compliance-critical information

If misunderstanding the help content could create compliance risk, keep it visible or use a linked disclosure.

Content guidelines

• Use plain-language labels. Government and financial forms require clarity.
• Mark required or optional fields. Use the required attribute on fd-label and the matching required attribute on the input. Include a visible page-level instruction explaining the asterisk convention (e.g., "Fields marked with * are required").
• Keep hint text to one sentence. Screen readers announce the full aria-describedby content on focus.
• Make InfoTip labels field-specific. The component auto-generates "More information about [label text]" by default. Override with infotip-label when more precision is needed.

Accessibility

• fd-label renders a native <label> element in light DOM, giving a real for/id association with the target input. Click-to-focus and screen reader name computation work natively.
• The required indicator uses a visual asterisk (aria-hidden="true") paired with visually-hidden text "(required)" for screen readers. The input itself must also have the required or aria-required attribute.
• Description text is auto-wired via aria-describedby on the target input. fd-label appends its description ID, preserves existing tokens, and cleans up only its own ID on disconnect.
• Sibling components such as fd-input use fd-label's stable public labelId and descriptionId getters internally. Consumers normally do not need to set or read these directly.
• The InfoTip uses the shared fd-infotip primitive: a real <button> with aria-expanded, aria-controls, and aria-describedby. No role="status" or live region. Escape closes the panel and returns focus to the trigger.
• Same-root limitation: The target control must share the same DOM root tree as fd-label. If the input lives inside another component's shadow root, the for/id association will not cross that boundary.

Known limitations

• Light DOM rendering — fd-label renders without a shadow root to enable native label association. This means host-page styles can bleed into the component. Styles are scoped via tag-qualified selectors (fd-label [part="..."]) and rendered as an inline <style> tag.
• No error slot — Error display stays in consuming form controls where it is coupled to validation state. fd-label is a labeling primitive, not a form field wrapper.
• InfoTip content is plain text only in v1 — The infotip attribute accepts a string. Rich content with links or interactive elements would require a dialog pattern and is out of scope.
• Popover API model — The InfoTip panel uses popover="auto" when available and keeps a narrow fallback path for test and older runtime surfaces.

Related components

• Radio Group — has built-in legend and description for grouped radio inputs
• Checkbox Group — has built-in legend and description for grouped checkboxes
• Selector — has built-in label and description for select-like inputs