FieldLabel

What it is

The text stack that identifies a field and reports its state: the label, an optional required-or-optional marker, and — beneath the field — helper text that becomes error text the moment the field is invalid. This page covers the whole labeling concept, not just the visible label word. FieldLabel is never used alone; every Forms component composes with it.

Live example

Exports

This page treats the label, helper text, and error text as one authored concept because a reader makes one decision about all three together.

Vocabulary

Term	Also called	The system uses
Field label	Title, caption	Field label — sits above a stacked field
Helper text	Hint, description, sub-label	Helper text
Error text	Validation message, field error	Error text — the same slot as helper text, swapped in when the field is invalid
Control label	Inline label, option label	Control label — sits beside a control, not above it
Tooltip icon	Info icon, help icon	Tooltip icon — an icon on the label itself that reveals extra guidance on demand

Field label and control label are two different layouts, not two words for one thing. A field label sits above a stacked control (Input, Select) and is what this page’s Tokens section calls form-label-font-weight. A control label sits inline beside Checkbox, Radio, or Switch, and is governed by a different token, form-control-label-min-height. Confusing the two produces a request for “the label’s font weight” against a component whose label is inline and unrelated to that token.

Choose FieldLabel when

A reader fills in or chooses a value for a field. There is no field exempted as “obvious enough” to skip a visible label — see TITAN-FLD-01.
The field needs to report something beyond present-or-absent: that it is required, that it failed validation, or a hint that a placeholder cannot hold once the reader starts typing.

Choose something else when

If you need to…	Use	Why
Label a control that already renders its own visible text	Nothing — the control’s content is its accessible name	A second label duplicates the control’s own text rather than adding information
Give a whole section of a form a heading, not one field a name	A heading inside Form	FieldLabel is scoped to a single field; a section needs a landmark, not a label
Show a short, optional clarification of the label itself	The label’s own tooltip icon	Confirmed as a real part of this component — see Anatomy — rather than a separate always-visible line

Anatomy

#	Part	Required
1	Label text	Yes
2	Optional marker	No — see TITAN-FLD-02
3	Tooltip icon	No — confirmed in the design library as `Tooltip Icon`, a boolean property of the label itself
4	Helper text	No
5	Error text	No — occupies the same slot as helper text; the two never render together

Variants, sizes, and states

Edge and failure states

Situation	What renders	Recovery
Label longer than the field is wide	Wraps to a second line — no truncation rule was found for this component	Needs confirmation — see Gaps
Both helper text and an error would apply at once	Error text replaces helper text; helper text does not render	Confirmed directly in `FormInput`’s source: the `helperText` prop is documented as “Hidden when `error` is set (error wins),” and the render logic shows `error` unconditionally over `helperText`. See TITAN-FLD-03
No helper text and no error	The slot renders nothing	The layout should not reserve empty space for a message that is not showing
Field is disabled	Label renders at `text-disabled`	—

Tokens

Composition

Pairs with every Forms component, in one of two positions per Vocabulary: above a stacked field (Input, Select, DatePicker) or beside an inline control (Checkbox, Radio, Switch). Reading order top to bottom for a stacked field is label, field, then helper or error text.

Content

Rule	✅	❌
Sentence case	Email address	Email Address
No terminal punctuation on the label	Email address	Email address:
Error text states the correction, not just the failure	Enter a valid email address	Invalid
Helper text answers “why,” error text answers “what to do”	Helper: We’ll send confirmations here. Error: Enter a valid email address.	Helper and error both restating the field name

Accessibility

Behavior
The label is programmatically associated with its field (`for`/`id`, or `aria-labelledby` for a composed control).
Helper and error text are associated via `aria-describedby`, and continue to be read even after the field itself has been announced.
An invalid field sets `aria-invalid="true"` in addition to swapping the visible text — the swap alone is not announced reliably by every screen reader.

What this component does not handle: deciding when a field is invalid, or moving focus to the first invalid field on submit — both belong to Form validation.

Constraints

ID	Constraint	Rationale
TITAN-FLD-01	Every field has a visible FieldLabel. Placeholder text is never the only label.	A placeholder disappears the moment the field has a value or focus, and is not read by every assistive technology as a label in the first place.
TITAN-FLD-03	Error text occupies the same slot as helper text. The two are never shown at once.	Two lines of guidance under one field competes for the same read; the more urgent one — the error — should be the only one showing.
TITAN-FLD-04	Error text states the correction, not only the failure.	”Invalid” tells the reader something is wrong and nothing about what to do next.
TITAN-FLD-05	Field labels are sentence case with no terminal punctuation. Proposed — assumed consistent with the sentence-case default for non-button UI text, not directly confirmed for field labels specifically. See TITAN-CASE-05.	Button labels are the confirmed exception, not the model — they’re title case. Field labels are assumed to follow the sentence-case default instead, matching error messages, until a source states otherwise.
TITAN-FLD-06	A field label is programmatically associated with its field, not merely adjacent to it visually.	Visual proximity is not a semantic relationship; a screen reader that has not been told the association will not announce the label with the field.
TITAN-FLD-07	A field’s tooltip icon supplements the label; it never carries information found nowhere else. A reader who cannot or does not open it must still be able to complete the field.	A tooltip’s content is not guaranteed to be read — hover-dependent content is unreliable on touch, and a reader who doesn’t notice the icon gets none of it.

Retired

ID	Was	Why retired
TITAN-FLD-02	Fields are required by default and unmarked. A field carries an explicit “optional” marker only when it is not required. Never the reverse (marking required fields instead).	The component’s API exposes only an “optional marker” property — there is no “required marker” to misuse in the first place. Retired, not reversed.

Known issues

FieldLabel: open issues

Divergences, open decisions, and undocumented gaps for FieldLabel.

Why it works this way

One slot for helper and error, not two. A field whose height changes when it becomes invalid moves every control below it — the same problem Button solves by holding its width while loading. Sharing one slot keeps a form’s layout stable regardless of validation state. Field label and control label are kept as separate vocabulary because they are separate layouts with separate tokens, not a single idea expressed two ways. Merging them would make “the label” ambiguous on exactly the two component types — checkboxes and switches — where getting the position wrong is most visible. Required is the unmarked default, optional is the marked exception, per TITAN-FLD-02, because most fields in a typical form are required — marking the majority case saves less reading than marking the minority case does.

Status

Input · Select · Checkbox — every field-style and control-style component composes with this one
Form validation — decides when a field is invalid
UI labels — casing and phrasing rules this page’s Content section follows

Overview

Actions

Forms

Data display

Navigation

Feedback

Containment

What it is

Live example

Exports

Vocabulary

Choose FieldLabel when

Choose something else when

Anatomy

Variants, sizes, and states

Edge and failure states

Tokens

Composition

Content

Accessibility

Constraints

Retired

Known issues

FieldLabel: open issues

Why it works this way

Status

​What it is

​Live example

​Exports

​Vocabulary

​Choose FieldLabel when

​Choose something else when

​Anatomy

​Variants, sizes, and states

​Edge and failure states

​Tokens

​Composition

​Content

​Accessibility

​Constraints

​Retired

​Known issues

FieldLabel: open issues

​Why it works this way

​Status

​Related

What it is

Live example

Exports

Vocabulary

Choose FieldLabel when

Choose something else when

Anatomy

Variants, sizes, and states

Edge and failure states

Tokens

Composition

Content

Accessibility

Constraints

Retired

Known issues

Why it works this way

Status

Related