TextField

TextField allows for text input.

Props

Component props
Name	Type	Default
`id` Required	`string`	-
	A unique identifier for the input.
`onChange` Required	`({\| event: SyntheticInputEvent<HTMLInputElement>, value: string, \|}) => void`	-
	Callback triggered when the value of the input changes.
`autoComplete`	`"current-password" \| "new-password" \| "on" \| "off" \| "username" \| "email"`	-
	Indicate if autocomplete should be available on the input, and the type of autocomplete.
`disabled`	`boolean`	`false`
	Indicate if the input is disabled.
`errorMessage`	`React.Node`	-
	For most use cases, pass a string with a helpful error message (be sure to localize!). In certain instances it can be useful to make some text clickable; to support this, you may instead pass a React.Node to wrap text in Link or TapArea.
`hasError`	`boolean`	`false`
	This field is deprecated and will be removed soon. Please do not use.
`helperText`	`string`	-
	More information about how to complete the form field.
`label`	`string`	-
	The label for the input. Be sure to localize the text.
`name`	`string`	-
	A unique name for the input.
`onBlur`	`({\| event: SyntheticFocusEvent<HTMLInputElement>, value: string, \|}) => void`	-
	Callback triggered when the user blurs the input.
`onFocus`	`({\| event: SyntheticFocusEvent<HTMLInputElement>, value: string, \|}) => void`	-
	Callback triggered when the user focuses the input.
`onKeyDown`	`({\| event: SyntheticKeyboardEvent<HTMLInputElement>, value: string, \|}) => void`	-
	Callback triggered when the user presses any key while the input is focused.
`placeholder`	`string`	-
	Placeholder text shown the the user has not yet input a value.
`size`	`"md" \| "lg"`	`"md"`
	md: 40px, lg: 48px
`tags`	`$ReadOnlyArray<React.Element<typeof Tag>>`	-
	List of tags to display in the component.
`type`	`"date" \| "email" \| "number" \| "password" \| "tel" \| "text" \| "url"`	`"text"`
	The type of input. For numerical input, please use NumberField.
`value`	`string`	-
	The current value of the input.

Usage guidelines

When to Use

Any time succinct data needs to be entered by a user, like a date, email address, name, or Pin title.

When Not to Use

Situations where long amounts of text need to be entered, since the full content of the TextField will be truncated. Use TextArea instead.

Example

TextField will expand to fill the width of the parent container.

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <TextField
      id="email"
      onChange={({ value }) => setValue(value)}
      placeholder="Add email"
      label="Email"
      value={value}
      type="email"
      autoComplete="email"
    />
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <TextField
      id="email"
      onChange={({ value }) => setValue(value)}
      placeholder="Add email"
      label="Email"
      value={value}
      type="email"
      autoComplete="email"
    />
  );
}

Example: Disabled

Disabled

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <TextField
      disabled
      id="name"
      onChange={({ value }) => setValue(value)}
      placeholder="Name"
      label="Disabled"
      value={value}
    />
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <TextField
      disabled
      id="name"
      onChange={({ value }) => setValue(value)}
      placeholder="Name"
      label="Disabled"
      value={value}
    />
  );
}

Example: Helper Text

Whenever you want to provide more information about a form field, you should use helperText.

Username

https://pinterest.com/

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box padding={2} color="white">
      <TextField
        id="username"
        helperText={'https://pinterest.com/' + value}
        onChange={({ value }) => setValue(value)}
        label="Username"
        value={value}
      />
    </Box>
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box padding={2} color="white">
      <TextField
        id="username"
        helperText={'https://pinterest.com/' + value}
        onChange={({ value }) => setValue(value)}
        label="Username"
        value={value}
      />
    </Box>
  );
}

Example: Error message

TextField can display an error message.
Simply pass in an errorMessage when there is an error present and we will handle the rest. Be sure to localize the text!

With an error message

This field can't be blank!

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <TextField
      id="aboutme"
      errorMessage={!value ? "This field can't be blank!" : null}
      onChange={({ value }) => setValue(value)}
      label="With an error message"
      value={value}
    />
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <TextField
      id="aboutme"
      errorMessage={!value ? "This field can't be blank!" : null}
      onChange={({ value }) => setValue(value)}
      label="With an error message"
      value={value}
    />
  );
}

Example: Tags

You can include Tag elements in the input using the tags prop.

Note that TextField does not internally manage tags. That should be handled in the application state through the component's event callbacks. We recommend creating new tags on enter key presses, and removing them on backspaces when the cursor is in the beginning of the field. We also recommend filtering out empty tags.

This example showcases the recommended behavior. In addition, it creates new tags by splitting the input on spaces, commas, semicolons.

Emails

a@pinterest.com

b@pinterest.com

function Example(props) {
  const [value, setValue] = React.useState('');
  const [tags, setTags] = React.useState(['a@pinterest.com', 'b@pinterest.com']);
  const ref = React.useRef();

  const onChangeTagManagement = ({ value }) => {
    // Create new tags around spaces, commas, and semicolons.
    const tagInput = value.split(/[\s,;]+/);
    if (tagInput.length > 1) {
      setTags([
        ...tags,
        // Avoid creating a tag on content after the separators, and filter out
        // empty tags
        ...tagInput.splice(0, tagInput.length - 1).filter(val => val !== ''),
      ]);
    }
    setValue(tagInput[tagInput.length - 1]);
  }

  const onKeyDownTagManagement = ({ event: { keyCode, target: { selectionEnd } } }) => {
    if (keyCode === 8 /* Backspace */ && selectionEnd === 0) {
      // Remove tag on backspace if the cursor is at the beginning of the field
      setTags([...tags.slice(0, -1)]);
    } else if (keyCode === 13 /* Enter */ && value.trim() !== '') {
      // Create a new tag on enter
      setTags([...tags, value.trim()]);
      setValue('');
    }
  }

  const renderedTags = tags.map((tag, idx) => (
    <Tag
      key={tag}
      onRemove={() => {
        const newTags = [...tags];
        newTags.splice(idx, 1);
        setTags([...newTags]);
        ref.current.focus();
      }}
      removeIconAccessibilityLabel={`Remove ${tag} tag`}
      text={tag}
    />
  ));

  return (
    <Box padding={2} color="white">
      <TextField
        autoComplete="off"
        id="tags"
        label="Emails"
        ref={ref}
        onChange={onChangeTagManagement}
        onKeyDown={onKeyDownTagManagement}
        tags={renderedTags}
        value={value}
      />
    </Box>
  );
}

function Example(props) {
  const [value, setValue] = React.useState('');
  const [tags, setTags] = React.useState(['a@pinterest.com', 'b@pinterest.com']);
  const ref = React.useRef();
  const onChangeTagManagement = ({ value }) => {
    // Create new tags around spaces, commas, and semicolons.
    const tagInput = value.split(/[\s,;]+/);
    if (tagInput.length > 1) {
      setTags([
        ...tags,
        // Avoid creating a tag on content after the separators, and filter out
        // empty tags
        ...tagInput.splice(0, tagInput.length - 1).filter(val => val !== ''),
      ]);
    }
    setValue(tagInput[tagInput.length - 1]);
  }
  const onKeyDownTagManagement = ({ event: { keyCode, target: { selectionEnd } } }) => {
    if (keyCode === 8 /* Backspace */ && selectionEnd === 0) {
      // Remove tag on backspace if the cursor is at the beginning of the field
      setTags([...tags.slice(0, -1)]);
    } else if (keyCode === 13 /* Enter */ && value.trim() !== '') {
      // Create a new tag on enter
      setTags([...tags, value.trim()]);
      setValue('');
    }
  }
  const renderedTags = tags.map((tag, idx) => (
    <Tag
      key={tag}
      onRemove={() => {
        const newTags = [...tags];
        newTags.splice(idx, 1);
        setTags([...newTags]);
        ref.current.focus();
      }}
      removeIconAccessibilityLabel={`Remove ${tag} tag`}
      text={tag}
    />
  ));
  return (
    <Box padding={2} color="white">
      <TextField
        autoComplete="off"
        id="tags"
        label="Emails"
        ref={ref}
        onChange={onChangeTagManagement}
        onKeyDown={onKeyDownTagManagement}
        tags={renderedTags}
        value={value}
      />
    </Box>
  );
}

Example: ref

TextField with an anchor ref to a Popover component

Focus the TextField to show the Popover

function TextFieldPopoverExample() {
  const [open, setOpen] = React.useState(false);
  const anchorRef = React.useRef();
  return (
    <Box marginBottom={12}>
      <TextField
        ref={anchorRef}
        label="Focus the TextField to show the Popover"
        id="my-example"
        onChange={() => {}}
        onBlur={() => setOpen(false)}
        onFocus={() => setOpen(true)}
      />
      {open && (
        <Popover
          anchor={anchorRef.current}
          idealDirection="down"
          onDismiss={() => setOpen(false)}
          shouldFocus={false}
          size="md"
        >
          <Box padding={3}>
            <Text weight="bold">Example with Popover</Text>
          </Box>
        </Popover>
      )}
    </Box>
  );
}

function TextFieldPopoverExample() {
  const [open, setOpen] = React.useState(false);
  const anchorRef = React.useRef();
  return (
    <Box marginBottom={12}>
      <TextField
        ref={anchorRef}
        label="Focus the TextField to show the Popover"
        id="my-example"
        onChange={() => {}}
        onBlur={() => setOpen(false)}
        onFocus={() => setOpen(true)}
      />
      {open && (
        <Popover
          anchor={anchorRef.current}
          idealDirection="down"
          onDismiss={() => setOpen(false)}
          shouldFocus={false}
          size="md"
        >
          <Box padding={3}>
            <Text weight="bold">Example with Popover</Text>
          </Box>
        </Popover>
      )}
    </Box>
  );
}

Autofocus

TextField intentionally lacks support for autofocus. Generally speaking,
autofocus interrupts normal page flow for screen readers making it an
anti-pattern for accessibility.

onSubmit

TextField is commonly used as an input in forms alongside submit buttons.
In these cases, users expect that pressing Enter or Return with the input
focused will submit the form.

Out of the box, TextField doesn't expose an onSubmit handler or
individual key event handlers due to the complexities of handling these
properly. Instead, developers are encouraged to wrap TextField
in a <form> and attach an onSubmit handler to that <form>.

Edit page on GitHub