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 aria-label="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

Storybook

Username

import { GlFormField, GlFormFieldLabel } from "gitlab-ui-react/form-field";
import { GlFormInput } from "gitlab-ui-react/form-input";

export default function FormInputExample() {
  return (
    <GlFormField className="max-w-md">
      <GlFormFieldLabel htmlFor="username">
        Username
      </GlFormFieldLabel>
      <GlFormInput defaultValue="Norcleeh" id="username" />
    </GlFormField>
  );
}

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

Maximum results

import {
  GlFormField,
  GlFormFieldGroup,
  GlFormFieldLabel,
} from "gitlab-ui-react/form-field";
import { GlFormInput } from "gitlab-ui-react/form-input";

export default function FormInputTypesExample() {
  return (
    <GlFormFieldGroup className="max-w-md">
      <GlFormField>
        <GlFormFieldLabel htmlFor="email">Email</GlFormFieldLabel>
        <GlFormInput id="email" placeholder="name@example.com" type="email" />
      </GlFormField>
      <GlFormField>
        <GlFormFieldLabel htmlFor="maximum-results">
          Maximum results
        </GlFormFieldLabel>
        <GlFormInput
          defaultValue={20}
          id="maximum-results"
          min={1}
          number
          type="number" />
      </GlFormField>
    </GlFormFieldGroup>
  );
}

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

Read-only value

Plain text value

Invalid value

Enter a supported value.

Disabled value

import {
  GlFormField,
  GlFormFieldError,
  GlFormFieldGroup,
  GlFormFieldLabel,
} from "gitlab-ui-react/form-field";
import { GlFormInput } from "gitlab-ui-react/form-input";

export default function FormInputStatesExample() {
  return (
    <GlFormFieldGroup className="max-w-md">
      <GlFormField>
        <GlFormFieldLabel htmlFor="readonly-value">
          Read-only value
        </GlFormFieldLabel>
        <GlFormInput
          defaultValue="Read-only value"
          id="readonly-value"
          readOnly />
      </GlFormField>
      <GlFormField>
        <GlFormFieldLabel htmlFor="plaintext-value">
          Plain text value
        </GlFormFieldLabel>
        <GlFormInput
          defaultValue="Plain text value"
          id="plaintext-value"
          plaintext />
      </GlFormField>
      <GlFormField>
        <GlFormFieldLabel htmlFor="invalid-value">
          Invalid value
        </GlFormFieldLabel>
        <GlFormInput
          aria-describedby="invalid-value-message"
          defaultValue="Invalid value"
          id="invalid-value"
          state={false} />
        <GlFormFieldError id="invalid-value-message">
          Enter a supported value.
        </GlFormFieldError>
      </GlFormField>
      <GlFormField>
        <GlFormFieldLabel htmlFor="disabled-value">
          Disabled value
        </GlFormFieldLabel>
        <GlFormInput
          defaultValue="Disabled value"
          disabled
          id="disabled-value" />
      </GlFormField>
    </GlFormFieldGroup>
  );
}

Accessibility

Associate every input with a visible GlFormFieldLabel using matching htmlFor and id values.
Placeholder text is a hint, not a replacement for a label.
Pair state={false} with visible feedback referenced by aria-describedby; aria-invalid is 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`

Usage

Default

Input types

States

Accessibility

API

Related resources