Components · Inputs
Text Input
A single line of free text. The most-used control in the suite, and the one whose states the rest of the input family follows.
Figma source: Text Input ↗Examples
<div class="cds-field">
<label class="cds-field__label" for="award">
Sponsor award number<span class="cds-field__required" aria-hidden="true">*</span>
</label>
<input class="cds-input" id="award" type="text" required
aria-describedby="award-help" placeholder="e.g. R01-GM-123456">
<span class="cds-field__caption" id="award-help">
Enter the number exactly as it appears on the sponsor's notice of award.
</span>
</div><!-- Validation fires on blur, and clears as soon as the value is fixed -->
<input class="cds-input" id="pi" type="text" required aria-describedby="pi-err" aria-invalid="false">
<span class="cds-field__error" id="pi-err" hidden>Enter the principal investigator's name.</span>States
The Figma file states it twice, for Text Input and again for Combobox: “No variant for error state with placeholder. Errors would only occur on inputs that have already had text.” and “No variant for focus state with placeholder. If user focuses on inputs, placeholder text is removed.”
That is correct behaviour, not a gap in the component set. A placeholder is visible only while the field is empty and unfocused; the moment it is focused or filled, the placeholder is gone, so a placeholder can never coexist with a focus ring or an error message.
Figma properties
| Property | Values | Notes |
|---|---|---|
State | Default · Focus · Disabled · Error | The four runtime states. |
Text Type | Blank · Placeholder · Entered | What the field currently contains. |
Show Icon? | boolean | A leading Font Awesome glyph. |
Icon code (fa) | text | The glyph name, e.g. search. |
Placeholder Copy | text | Format hint shown while blank and unfocused. |
Input Text | text | The entered value. |
Usage
When to use it
- Use for short, free-form, single-line text — names, titles, identifiers.
- Size the field to the expected content: a five-character code should not sit in a 400px box.
- Use
typeto get the right mobile keyboard and browser validation —email,tel,url. - Put format requirements in persistent help text, not the placeholder.
Placeholder text disappears the moment the user types, taking the field’s only description
with it — which breaks anyone relying on short-term memory, anyone interrupted mid-form, and
anyone reviewing their answers before submitting. It also sits at
--input-caption grey, which is deliberately low-emphasis.
Every field needs a persistent <label>. Use the placeholder only for a
format hint that supplements the label — never to replace it.
Accessibility
- Every input needs a
<label for>matching itsid. A visually hidden label is acceptable where the layout truly cannot carry one; no label is not. - Bind help text and error text with
aria-describedbyso both are announced with the field. - Set
aria-invalid="true"when the field is in error, and back tofalsewhen fixed. - The asterisk is decorative —
aria-hidden="true"— with the realrequiredattribute carrying the meaning. - Error text is 12px. It must never be the only signal: the border also thickens to 2px and turns red.
Tokens consumed
| Token | Applied to | Resolves to |
|---|---|---|
--input-background | Field fill | --color-white |
--input-border | Resting border | --color-gray-400 → #888c8c |
--input-text | Entered value | --color-black → #111111 |
--input-focus-border | Focus ring | --focus-ring → #44a3db ⚠ |
--input-error-background | Fill in error | --color-red-100 |
--input-error-border | Border in error | --color-red-500 |
--input-disabled-background | Fill when disabled | --color-gray-100 |
--input-disabled-text | Value when disabled | --disabled-text → #888c8c |
--input-label | Label | --color-black |
--input-required | Required asterisk | --color-red-500 |
--input-caption | Help text and placeholder | --color-gray-500 |
--input-error-caption | Error message | --color-red-500 |