Form input
Captures a single-line text, numeric, date, or other native input value.
On this page
This docs is LLM-friendly and available as clean Markdown.
Usage
import { GlFormInput } from "gitlab-ui-react/form-input";<GlFormInput id="username" />Default
The default component renders a native text input. Always pair it with a visible label that describes the value rather than its presentation.
Text input
import { GlFormInput } from "gitlab-ui-react/form-input";
export default function FormInputExample() {
return (
<div className="max-w-md">
<label className="mb-2 block font-bold" htmlFor="username">
Username
</label>
<GlFormInput defaultValue="Norcleeh" id="username" />
</div>
);
}
Input types
Set type for supported native inputs such as email, number, URL, telephone, search, date, time, range, and color. Browser behavior and appearance can vary by type.
Input types
import { GlFormInput } from "gitlab-ui-react/form-input";
export default function FormInputTypesExample() {
return (
<div className="grid max-w-md gap-4">
<div>
<label className="mb-2 block font-bold" htmlFor="email">Email</label>
<GlFormInput id="email" placeholder="name@example.com" type="email" />
</div>
<div>
<label className="mb-2 block font-bold" htmlFor="maximum-results">
Maximum results
</label>
<GlFormInput
defaultValue={20}
id="maximum-results"
min={1}
number
type="number" />
</div>
</div>
);
}
States
Use readOnly when a value remains focusable, selectable, and submitted. Use disabled only when the input should be inert, and pair invalid state with explanatory feedback.
Input states
Enter a supported value.
import { GlFormInput } from "gitlab-ui-react/form-input";
export default function FormInputStatesExample() {
return (
<div className="grid max-w-md gap-4">
<GlFormInput aria-label="Read-only value" defaultValue="Read-only value" readOnly />
<GlFormInput aria-label="Plain text value" defaultValue="Plain text value" plaintext />
<div className="grid gap-2">
<GlFormInput
aria-describedby="invalid-value-message"
aria-label="Invalid value"
defaultValue="Invalid value"
state={false} />
<p
id="invalid-value-message"
className="m-0"
style={{ color: "var(--gl-control-text-color-error)" }}>
Enter a supported value.
</p>
</div>
<GlFormInput aria-label="Disabled value" defaultValue="Disabled value" disabled />
</div>
);
}
Accessibility
- Associate every input with a visible
<label>using matchinghtmlForandidvalues. - Placeholder text is a hint, not a replacement for a label.
- Pair
state={false}with visible feedback referenced byaria-describedby;aria-invalidis set automatically. - Use the native input type that best communicates the expected value and enables the appropriate browser keyboard.
- Avoid autofocus unless moving focus is essential and will not surprise the user.
API
GlFormInput accepts supported Base UI input and native attributes and forwards its ref to the <input> element.
| Prop | Description | Default |
|---|---|---|
type |
Sets a supported native input type; unsupported values fall back to text. |
"text" |
value |
Controls the input value as a string or number. | — |
defaultValue |
Sets the initial uncontrolled value. | "" |
onValueChange |
Reports the value after formatting, debounce, and value modifiers. | — |
state |
Sets valid, invalid, or neutral appearance. | null |
readOnly |
Prevents editing while keeping the value focusable and submitted. | false |
plaintext |
Renders a borderless, read-only value. | false |
width |
Sets a fixed or responsive width from xs through xl. |
null |
debounce |
Delays onValueChange by the given milliseconds. |
0 |
lazy |
Reports value changes on change or blur instead of each keystroke. | false |
formatter |
Transforms input text or cancels an update by returning false. |
— |
number |
Converts a numeric value to a number when possible. | false |
trim |
Removes leading and trailing whitespace from the reported value. | false |