Skip to main content
On this page

Text Field

A form field for accepting text inputs

When to use​

  • When the user needs to input specific information that cannot be predicted from a predefined list, for instance their name
  • When the input is memorable information that will be quicker to type by hand than interact with a more structured input
  • When it is essential to avoid bias - predefined lists can force users to pick a choice they don't actually agree with

When not to use​

  • When only an item from a predefined list will be accepted - this is likely to result in an error. Use Radio, Checkbox, or Select Field instead.
  • For large text inputs - users will not be able to see what they have entered easily. Use TextArea Field instead.
  • To indicate that a field is unavailable - the disabled state is not supported. Use Summary List to show values that cannot be edited, or conditionally hide the field if it is not relevant in the current context.

Anatomy​

  1. Label
  2. Hint
  3. Input
  4. Left icon - optional
  5. Right icon - optional
  6. Error message
  7. Required/Optional indicator

Basic usage​

Loading...
Edit live code
<TextField id="name" label="Name" />

Variants and features​

Input types​

TextField has four specialised variants for specific input types. These are separate components that share the TextField API.

  • NumberField - for numeric input
  • EmailField - for email addresses
  • TelField - for telephone numbers
  • PasswordField - for passwords. Characters are masked as the user types. Always provide hint text listing any requirements for the password format, such as the types of characters allowed.
Loading...
Edit live code
<Stack spaceBetween={4}>
  <NumberField id="age-2" label="Age" characters={4} />
  <EmailField id="email-types" label="Email address" characters={25} />
  <TelField id="tel" label="Mobile" characters={11} />
  <PasswordField
    id="password-types"
    label="Password"
    hint="At least 12 characters, including a number"
    characters={20}
  />
</Stack>

Left and right icons​

Use the iconLeft or iconRight props to display an icon inside the input.

Loading...
Edit live code
<Stack spaceBetween={4}>
  <TextField id="search-icon" label="Search accounts" iconLeft="search-empty" />
  <TextField id="external-icon" label="Reference" iconRight="new-window" />
</Stack>

Common form features​

The following features are shared across all Nebula form fields. See Form guidance for full detail.

Validation and errors - when a field is invalid, an error message appears below the input and the input border changes to indicate the error state.

Hint text - use the hint prop to provide additional context to help the user complete the field correctly. Keep hint text brief and specific to the field.

Required and optional - fields are required by default. Use the optional prop to mark a field as optional. The required or optional state is indicated visually as part of the label.

Field width - use the characters prop to set the input width to match the expected length of the content. Making inputs the right size for what they collect helps the user understand what to enter. TextField is responsive by default and displays full width below the smallest breakpoint - override with fullWidth="always" or fullWidth="never".

Loading...
Edit live code
<Stack spaceBetween={4}>
  <TextField
    id="form-features-error"
    label="Account name"
    error="Enter an account name"
  />
  <TextField
    id="form-features-hint"
    label="Account number"
    hint="8 digits, found at the top of your bill"
  />
  <TextField id="form-features-optional" label="Middle name" optional />
  <TextField id="form-features-width" label="Postcode" characters={8} />
</Stack>

Grouping​

Text fields are typically part of a larger form. See the Form component and form guidelines for guidance on grouping and layout.