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.
Supported browser agents can also use WebMCP to search, read, and open these docs. Learn more
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.
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.
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.
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 |