TextField

TextFields are text inputs that allow users to input custom text entries with a keyboard. Various decorations can be displayed around the field to communicate the entry requirements.

Example#

<TextField label="Name" />

<TextField label="Name" />

<TextField label="Name" />

Value#

A TextField's value is empty by default, but an initial, uncontrolled, value can be provided using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.

function Example() {
  let [value, setValue] = React.useState('me@email.com');

  return (
    <Flex gap="size-150" wrap>
      <TextField
        label="Email (Uncontrolled)"
        defaultValue="me@email.com" />

      <TextField
        label="Email (Controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}

function Example() {
  let [value, setValue] = React.useState('me@email.com');

  return (
    <Flex gap="size-150" wrap>
      <TextField
        label="Email (Uncontrolled)"
        defaultValue="me@email.com" />

      <TextField
        label="Email (Controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}

function Example() {
  let [value, setValue] =
    React.useState(
      'me@email.com'
    );

  return (
    <Flex
      gap="size-150"
      wrap
    >
      <TextField
        label="Email (Uncontrolled)"
        defaultValue="me@email.com"
      />

      <TextField
        label="Email (Controlled)"
        value={value}
        onChange={setValue}
      />
    </Flex>
  );
}

HTML forms#

TextField supports the name prop for integration with HTML forms. In addition, attributes such as type, pattern, inputMode, and others are passed through to the underlying <input> element.

<TextField label="Email" name="email" type="email" />

<TextField label="Email" name="email" type="email" />

<TextField
  label="Email"
  name="email"
  type="email"
/>

Labeling#

A visual label should be provided for the TextField using the label prop. If the TextField is required, the isRequired and necessityIndicator props can be used to show a required state.

<Flex gap="size-150" wrap>
  <TextField label="Street address" />
  <TextField label="Street address" isRequired necessityIndicator="icon" />
  <TextField label="Street address" isRequired necessityIndicator="label" />
  <TextField label="Street address" necessityIndicator="label" />
</Flex>

<Flex gap="size-150" wrap>
  <TextField label="Street address" />
  <TextField
    label="Street address"
    isRequired
    necessityIndicator="icon"
  />
  <TextField
    label="Street address"
    isRequired
    necessityIndicator="label"
  />
  <TextField
    label="Street address"
    necessityIndicator="label"
  />
</Flex>

<Flex
  gap="size-150"
  wrap
>
  <TextField label="Street address" />
  <TextField
    label="Street address"
    isRequired
    necessityIndicator="icon"
  />
  <TextField
    label="Street address"
    isRequired
    necessityIndicator="label"
  />
  <TextField
    label="Street address"
    necessityIndicator="label"
  />
</Flex>

Accessibility#

If a visible label isn't specified, an aria-label must be provided to the TextField for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Internationalization#

In order to internationalize a TextField, a localized string should be passed to the label or aria-label prop. When the necessityIndicator prop is set to "label", a localized string will be provided for "(required)" or "(optional)" automatically.

Events#

TextField accepts an onChange prop which is triggered whenever the value is edited by the user. For a full list of supported events, see the Props table below.

The example below uses onChange to update a separate pre element with the same text entered into the TextField.

function Example() {
  let [text, setText] = React.useState('');

  return (
    <Flex direction="column" gap="size-150">
      <TextField
        onChange={setText}
        label="Your text" />
      <pre>Mirrored text: {text}</pre>
    </Flex>
  );
}

function Example() {
  let [text, setText] = React.useState('');

  return (
    <Flex direction="column" gap="size-150">
      <TextField
        onChange={setText}
        label="Your text" />
      <pre>Mirrored text: {text}</pre>
    </Flex>
  );
}

function Example() {
  let [text, setText] =
    React.useState('');

  return (
    <Flex
      direction="column"
      gap="size-150"
    >
      <TextField
        onChange={setText}
        label="Your text"
      />
      <pre>Mirrored text: {text}</pre>
    </Flex>
  );
}

Validation#

TextField supports native HTML constraint validation props such as isRequired, type="email", minLength, and pattern, as well as custom validation functions, realtime validation, and server-side validation. It can also be integrated with other form libraries. See the Forms guide to learn more.

When the Form component has the validationBehavior="native" prop, validation errors block form submission and are displayed as help text automatically. Errors are displayed when the user blurs the text field or submits the form.

import {Form, ButtonGroup, Button} from '@adobe/react-spectrum';

<Form validationBehavior="native" maxWidth="size-3000">
  <TextField label="Email" name="email" type="email" isRequired />  <ButtonGroup>
    <Button type="submit" variant="primary">Submit</Button>
    <Button type="reset" variant="secondary">Reset</Button>
  </ButtonGroup>
</Form>

import {
  Button,
  ButtonGroup,
  Form
} from '@adobe/react-spectrum';

<Form validationBehavior="native" maxWidth="size-3000">
  <TextField
    label="Email"
    name="email"
    type="email"
    isRequired
  />  <ButtonGroup>
    <Button type="submit" variant="primary">
      Submit
    </Button>
    <Button type="reset" variant="secondary">
      Reset
    </Button>
  </ButtonGroup>
</Form>

import {
  Button,
  ButtonGroup,
  Form
} from '@adobe/react-spectrum';

<Form
  validationBehavior="native"
  maxWidth="size-3000"
>
  <TextField
    label="Email"
    name="email"
    type="email"
    isRequired
  />  <ButtonGroup>
    <Button
      type="submit"
      variant="primary"
    >
      Submit
    </Button>
    <Button
      type="reset"
      variant="secondary"
    >
      Reset
    </Button>
  </ButtonGroup>
</Form>

By default, TextField displays default validation messages provided by the browser. See Customizing error messages in the Forms guide to learn how to provide your own custom errors.

Props#

Visual options#

Quiet#

View guidelines

<TextField label="Email" isQuiet />

<TextField label="Email" isQuiet />

<TextField
  label="Email"
  isQuiet
/>

Disabled#

View guidelines

<TextField label="Email" isDisabled />

<TextField label="Email" isDisabled />

<TextField
  label="Email"
  isDisabled
/>

Read only#

The isReadOnly boolean prop makes the TextField's text content immutable. Unlike isDisabled, the TextField remains focusable and the contents can still be copied. See the MDN docs for more information.

<TextField label="Email" defaultValue="abc@adobe.com" isReadOnly />

<TextField
  label="Email"
  defaultValue="abc@adobe.com"
  isReadOnly
/>

<TextField
  label="Email"
  defaultValue="abc@adobe.com"
  isReadOnly
/>

Label alignment and position#

View guidelines

By default, the label is positioned above the TextField. The labelPosition prop can be used to position the label to the side. The labelAlign prop can be used to align the label as "start" or "end". For left-to-right (LTR) languages, "start" refers to the left most edge of the TextField and "end" refers to the right most edge. For right-to-left (RTL) languages, this is flipped.

<TextField label="Search" labelPosition="side" labelAlign="end" />

<TextField
  label="Search"
  labelPosition="side"
  labelAlign="end"
/>

<TextField
  label="Search"
  labelPosition="side"
  labelAlign="end"
/>

Help text#

View guidelines

Both a description and an error message can be supplied to a TextField. The description is always visible unless the validationState is “invalid” and an error message is provided. The error message can be used to help the user fix their input quickly and should be specific to the detected error. All strings should be localized.

<Flex gap="size-100" wrap>
  <TextField
    label="Name"
    defaultValue="John"
    validationState="valid"
    description="Enter your name."
  />
  <TextField
    label="Name"
    validationState="invalid"
    errorMessage="Empty input is not allowed."
  />
</Flex>

<Flex gap="size-100" wrap>
  <TextField
    label="Name"
    defaultValue="John"
    validationState="valid"
    description="Enter your name."
  />
  <TextField
    label="Name"
    validationState="invalid"
    errorMessage="Empty input is not allowed."
  />
</Flex>

<Flex
  gap="size-100"
  wrap
>
  <TextField
    label="Name"
    defaultValue="John"
    validationState="valid"
    description="Enter your name."
  />
  <TextField
    label="Name"
    validationState="invalid"
    errorMessage="Empty input is not allowed."
  />
</Flex>

Contextual help#

A ContextualHelp element may be placed next to the label to provide additional information or help about a TextField.

import {Content, ContextualHelp, Heading} from '@adobe/react-spectrum';

<TextField
  label="Password"
  type="password"
  contextualHelp={
    <ContextualHelp>
      <Heading>Need help?</Heading>
      <Content>
        If you're having trouble accessing your account, contact our customer
        support team for help.
      </Content>
    </ContextualHelp>
  }
/>

import {
  Content,
  ContextualHelp,
  Heading
} from '@adobe/react-spectrum';

<TextField
  label="Password"
  type="password"
  contextualHelp={
    <ContextualHelp>
      <Heading>Need help?</Heading>
      <Content>
        If you're having trouble accessing your account,
        contact our customer support team for help.
      </Content>
    </ContextualHelp>
  }
/>

import {
  Content,
  ContextualHelp,
  Heading
} from '@adobe/react-spectrum';

<TextField
  label="Password"
  type="password"
  contextualHelp={
    <ContextualHelp>
      <Heading>
        Need help?
      </Heading>
      <Content>
        If you're
        having trouble
        accessing your
        account,
        contact our
        customer
        support team
        for help.
      </Content>
    </ContextualHelp>
  }
/>

Custom width#

View guidelines

<TextField label="Email" width="size-3600" maxWidth="100%" />

<TextField
  label="Email"
  width="size-3600"
  maxWidth="100%"
/>

<TextField
  label="Email"
  width="size-3600"
  maxWidth="100%"
/>