TextField allows for multiple types of text input.

also known as Text Input

Figma:

Responsive:

Adaptive:

A11y:

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
"bday" | "current-password" | "email" | "new-password" | "on" | "off" | "username" | 52 more ...
-

Indicate if autocomplete should be available on the input, and the type of autocomplete. All autocomplete values are supported.

dataTestId
string
-

Available for testing purposes, if needed. Consider better queries before using this prop.

disabled
boolean
false

Indicate if the input is disabled. See the disabled example for more details.

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.

labelDisplay
"visible" | "hidden"
"visible"

Whether the label should be visible or not. If hidden, the label is still available for screen reader users, but does not appear visually. See the label visibility variant for more info.

maxLength
{
  characterCount: number,
  errorAccessibilityLabel: string,
}
-

The maximum number of characters allowed in Textfield. maxLength must be an integer value 0 or higher. See the maximum length variant for more details.

mobileEnterKeyHint
"enter" | "done" | "go" | "next" | "previous" | "search" | "send"
-

Mobile only prop. Optionally specify the action label to present for the enter key on virtual keyboards. See the enterKeyHint variant for more info.

mobileInputMode
"none" | "text" | "decimal" | "numeric"
-

Mobile only prop. Optionally specify the type of data that might be entered by the user while editing the element or its contents. This allows mobile browsers to display an appropriate virtual keyboard. See the enterKeyHint variant for more info.

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.

readOnly
boolean
false

Indicate if the input is readOnly. See the readOnly example for more details.

ref
React.Element<"input">
-

Ref that is forwarded to the underlying input element.

size
"sm" | "md" | "lg"
"md"

Defines the height of the TextField: sm: 32px, md: 40px (default), lg: 48px. See the size variant for more details.

tags
$ReadOnlyArray<React.Element<typeof Tag>>
-

List of tags to display in the component.

type
"date" | "email" | "password" | "tel" | "text" | "url"
"text"

The type of input. For non-telephone 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.

Best practices

Do

Use helper text for important information. Helper text helps users understand how to complete the text field or to indicate any needed input.

Don't

Put essential information in the placeholder text, since it disappears when the user types. The placeholder text is not a replacement for the label.

Do

Always ensure the text field has a visible label. The label provides context and supports users when filling in information.

Don't

Remove the label, as this creates accessibility and usability issues.

Do

Only place related fields on the same line.

Don't

Place unrelated text fields on the same line, as this can create comprehension issues.

Do

Provide clear and useful error messages that help the user fix the issue. Error messages should be displayed in a timely manner — typically once the field loses focus or when the form is submitted.

Don't

Display generic error messages, such as "There is an error".

Do

Consider all text fields as required, unless explicitly noted as optional.

Don't

Mark fields as required.

Accessibility

Comprehension

Be sure to provide instructions to help users understand how to complete the form and use individual form controls.

Labels

TextField comes with Label built-in: just use the label prop. We strongly encourage always supplying a label. Be sure to provide a unique id so the Label is associated with the correct TextField.

If TextField is labeled by content elsewhere on the page, or a more complex label is needed, the labelDisplay prop can be used to visually hide the label. In this case, it is still available to screen reader users, but will not appear visually on the screen.

import { Box, Flex, Text, TextField } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex gap={{ column: 0, row: 6 }}>
        <TextField
          id="textfieldexampleA11yVisible"
          label="First name"
          onChange={() => {}}
          size="lg"
        />
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text size="300" weight="bold">
            First name
          </Text>
          <TextField
            id="textfieldexampleA11yHiddenLabel"
            label="First name"
            labelDisplay="hidden"
            onChange={() => {}}
            size="lg"
          />
        </Flex>
      </Flex>
    </Box>
  );
}

Validation

When providing a validation message, make sure the instructions are clear and help users complete the field. For example, "Passwords must contain at least 20 characters". In addition, use the helper text to provide instructions to help users understand how to complete the text field or to indicate any needed input, allowed formats, timing limitations, or other pertinent information.

These practices give users of assistive technologies more information about the form, helping them to fill it out.

Keyboard navigation

TextField has conventional keyboard support.

  • Users relying on the keyboard expect to move focus to each TextField by using the tab key or shift+tab when moving backwards.
  • Setting disabled will prevent TextField from receiving keyboard focus or input.

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> with an onSubmit handler..

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

TextField depends on DefaultLabelProvider for internal text strings. Localize the texts via DefaultLabelProvider. Learn more
import { useState } from 'react';
import { Box, DefaultLabelProvider, TextField } from 'gestalt';

export default function Example() {
  const [password, setPassword] = useState('');

  return (
    <DefaultLabelProvider
      // $FlowExpectedError[incompatible-type] For demostration purposes
      labels={{
        TextField: {
          accessibilityHidePasswordLabel: 'Passwort verstecken',
          accessibilityShowPasswordLabel: 'Passwort anzeigen',
        },
      }}
    >
      <Box
        alignItems="center"
        display="flex"
        height="100%"
        justifyContent="center"
        padding={8}
      >
        <TextField
          id="enter-password"
          label="Konto-Passwort"
          onChange={({ value }) => setPassword(value)}
          placeholder="Kennwort"
          type="password"
          value={password}
        />
      </Box>
    </DefaultLabelProvider>
  );
}

Variants

Helper text

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

import { useState } from 'react';
import { Box, TextField } from 'gestalt';

export default function Example() {
  const [value, setValue] = useState('');

  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Box color="light" padding={2}>
        <TextField
          autoComplete="new-password"
          helperText="Password should be at least 20 characters long"
          id="variants-helper-text"
          label="Password"
          onChange={(e) => {
            setValue(e.value);
          }}
          type="password"
          value={value}
        />
      </Box>
    </Box>
  );
}

Label visibility

In some cases, the label for a TextField is represented in a different way visually, as demonstrated below. In these instances, you can set labelDisplay="hidden" to ensure TextField is properly labeled for screen readers while using a different element to represent the label visually.

import { Box, Flex, Text, TextField } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Text size="300" weight="bold">
          First name
        </Text>
        <TextField
          id="textfieldexampleHiddenLabel"
          label="First name"
          labelDisplay="hidden"
          onChange={() => {}}
          size="lg"
        />
      </Flex>
    </Box>
  );
}

Read-only

Read-only TextFields are used to present information to the user without allowing them to edit the content. Typically they are used to show content or information that the user does not have permission or access to edit.

import { useState } from 'react';
import { Box, TextField } from 'gestalt';

export default function Example() {
  const [value, setValue] = useState('****maz@pinterest.com');

  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <TextField
        id="variants-readonly"
        label="Email address"
        onChange={(e) => setValue(e.value)}
        placeholder="Name"
        readOnly
        value={value}
      />
    </Box>
  );
}

Password

TextField with type="password" shows obfuscated characters by default. An icon button at the end of the field allows the user to toggle password visibility. This creates a more accessible experience by allowing the user to confirm what they have entered before submitting the form.

import { useState } from 'react';
import { Box, TextField } from 'gestalt';

export default function Example() {
  const [password, setPassword] = useState('');

  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <TextField
        id="enter-password"
        label="Account password"
        onChange={({ value }) => setPassword(value)}
        placeholder="Password"
        type="password"
        value={password}
      />
    </Box>
  );
}

Disabled

disabled TextFields cannot be interacted with using the mouse or keyboard. They also do not need to meet contrast requirements, so do not use them to present info to the user (use readOnly instead).

import { useState } from 'react';
import { Box, TextField } from 'gestalt';

export default function Example() {
  const [value, setValue] = useState('');

  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <TextField
        disabled
        id="variants-disabled"
        label="New password"
        onChange={(e) => {
          setValue(e.value);
        }}
        placeholder="6-18 characters"
        value={value}
      />
    </Box>
  );
}

Error message

TextField can display an error message. Simply pass in an errorMessage when there is an error present and TextField will handle the rest.
Don't use errorMessage to provide feedback on character count errors. See the maximum length variant for more details.

import { useState } from 'react';
import { Box, TextField } from 'gestalt';

export default function Example() {
  const [value, setValue] = useState('');

  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <TextField
        errorMessage={!value ? "This field can't be blank!" : null}
        id="variants-error-message"
        label="New username"
        onChange={(e) => {
          setValue(e.value);
        }}
        value={value}
      />
    </Box>
  );
}

Tags

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

Note that TextField does not internally manage tags. Tag management 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, and semicolons.

import { useRef, useState } from 'react';
import { Box, Tag, TextField } from 'gestalt';

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

  const onChangeTagManagement = (e) => {
    // Create new tags around spaces, commas, and semicolons.
    const tagInput = e.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,
      currentTarget: { 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}
      accessibilityRemoveIconLabel={`Remove ${tag} tag`}
      onRemove={() => {
        const newTags = [...tags];
        newTags.splice(idx, 1);
        setTags([...newTags]);
        if (ref.current) {
          ref.current.focus();
        }
      }}
      text={tag}
    />
  ));

  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Box color="light" padding={2}>
        <TextField
          ref={ref}
          autoComplete="off"
          id="variants-tags"
          label="Emails"
          onChange={onChangeTagManagement}
          onKeyDown={onKeyDownTagManagement}
          tags={renderedTags}
          value={value}
        />
      </Box>
    </Box>
  );
}

Mobile

TextField supports some props to improve the mobile experience. Browsers display virtual keyboard when the user interacts with TextField. enterKeyHint and inputMode allow customizing the virtual keyboard for a better data input.

The mobileEnterKeyHint prop presents to the user a more accurate action label for the enter key on virtual keyboards. These are the values for each use case:

  • "enter": inserting a new line
  • "done": there is nothing more to input and the input editor will be closed
  • "go": taking the user to the target of the text they typed
  • "next": taking the user to the next field that will accept text
  • "previous": taking the user to the previous field that will accept text
  • "search": taking the user to the results of searching for the text they have typed
  • "send": delivering the text to its target

The mobileInputMode prop presents to the user a more accurate action label for the enter key on virtual keyboards. These are the values for each use case:

  • "none": No virtual keyboard. For when the page implements its own keyboard input control, for example DatePicker displays the calendar picker.
  • "text": Standard input keyboard for the user's current locale.
  • "decimal": Fractional numeric input keyboard containing the digits and decimal separator for the user's locale (typically "." or ",").
  • "numeric": Numeric input keyboard, but only requires the digits 0–9.

Use type when TextField needs to capture phone numbers, emails or URLs.

import { Box, Flex, Image, TextField } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex gap={2}>
        <TextField
          id="enterKeyHint"
          label="Text virtual keyboard with 'next'"
          mobileEnterKeyHint="next"
          onBlur={() => {}}
          onChange={() => {}}
          onFocus={() => {}}
        />
        <Box height={100} width={200}>
          <Image
            alt="Image of a screenshot of a virtual keyboard on a mobile screen showing a text virtual keyboard with 'next'"
            naturalHeight={1}
            naturalWidth={1}
            src="https://i.ibb.co/qdMLb8t/IMG-2518.jpg"
          />
        </Box>
      </Flex>
    </Box>
  );
}

Text virtual keyboard with 'next'
import { Box, Flex, Image, TextField } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex gap={2}>
        <TextField
          id="decimal"
          label="Decimal virtual keyboard"
          mobileInputMode="decimal"
          onBlur={() => {}}
          onChange={() => {}}
          onFocus={() => {}}
        />
        <Box height={100} width={200}>
          <Image
            alt="Image of a screenshot of a virtual keyboard on a mobile screen showing a decimal virtual keyboard"
            naturalHeight={1}
            naturalWidth={1}
            src="https://i.ibb.co/WxYtCdx/IMG-2520.jpg"
          />
        </Box>
      </Flex>
    </Box>
  );
}

import { Box, Flex, Image, TextField } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex gap={2}>
        <TextField
          id="none"
          label="Numeric virtual keyboard"
          mobileInputMode="numeric"
          onBlur={() => {}}
          onChange={() => {}}
          onFocus={() => {}}
          type="date"
        />
        <Box height={100} width={200}>
          <Image
            alt="Image of a screenshot of a virtual keyboard on a mobile screen showing a numeric virtual keyboard"
            naturalHeight={1}
            naturalWidth={1}
            src="https://i.ibb.co/tpZ9pV8/IMG-2519.jpg"
          />
        </Box>
      </Flex>
    </Box>
  );
}

import { Box } from 'gestalt';
import { DatePicker } from 'gestalt-datepicker';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <DatePicker
        id="datepicker"
        label="No virtual keyboard"
        onChange={() => {}}
      />
    </Box>
  );
}

Maximum length

Textfield supports the native maxlength input attribute. maxLength sets the maximum number of characters allowed to be entered by the user in Textfield. maxLength must be an integer value 0 or higher.

The user cannot exceed the maximum number of characters interacting with the component. Whenever possible, avoid setting initial values from the parent component's state that already exceed the maxLength.

When maxLength is passed to TextField, the component displays a character counter as well as a warning or problem Status when the user reaches or the prepopulated controlled value exceeds the maximum length of characters.

The first example shows an empty Textfield with maxLength set to 20 characters. The second example shows the warning and problem Status.

import { useState } from 'react';
import { Box, TextField } from 'gestalt';

export default function TextFieldExample() {
  const [value, setValue] = useState('');
  const characterCount = 20;

  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <TextField
        helperText="Enter a title that captures the imagination of Pinners"
        id="maxLength"
        label="Title"
        maxLength={{
          characterCount,
          errorAccessibilityLabel:
            'Limit reached. You can only use 20 characters in this field.',
        }}
        onBlur={() => {}}
        onChange={(e) => setValue(e.value)}
        onFocus={() => {}}
        placeholder="Enter your pin title"
        value={value}
      />
    </Box>
  );
}

import { useState } from 'react';
import { Box, Flex, TextField } from 'gestalt';

export default function TextFieldExample() {
  const [valueA, setValueA] = useState('Delicious vegan soup');
  const [valueB, setValueB] = useState('Delicious vegan noodle soup');

  const characterCount = 20;
  const errorAccessibilityLabel =
    'Limit reached. You can only use 20 characters in this field.';

  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex direction="column" gap={12}>
        <TextField
          helperText="Enter a title that captures the imagination of Pinners"
          id="maxLengthReached"
          label="Title"
          maxLength={{ characterCount, errorAccessibilityLabel }}
          onBlur={() => {}}
          onChange={({ value }) => setValueA(value)}
          onFocus={() => {}}
          placeholder="Enter your pin title"
          value={valueA}
        />
        <TextField
          helperText="Enter a title that captures the imagination of Pinners"
          id="maxLengthExceeded"
          label="Title"
          maxLength={{ characterCount, errorAccessibilityLabel }}
          onBlur={() => {}}
          onChange={({ value }) => setValueB(value)}
          onFocus={() => {}}
          placeholder="Enter your pin title"
          value={valueB}
        />
      </Flex>
    </Box>
  );
}

Refs

TextField can accept a ref for anchoring Popover-based components.

import { useRef, useState } from 'react';
import { Box, Popover, Text, TextField } from 'gestalt';

export default function TextFieldPopoverExample() {
  const [open, setOpen] = useState(false);
  const anchorRef = useRef(null);

  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Box color="light" padding={2}>
        <TextField
          ref={anchorRef}
          id="variants-refs"
          label="Focus the TextField to show the Popover"
          onBlur={() => {
            setOpen(false);
          }}
          onChange={() => {}}
          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>
    </Box>
  );
}

Size

TextField can have different sizes. The default size is md (40px). The lg size is 48px. For a dense variant, use the sm (32px) variant.

import { useState } from 'react';
import { Box, Flex, Heading, TextField } from 'gestalt';

export default function TextFieldSizes() {
  const [input1text, setInput1Text] = useState('');
  const [input2text, setInput2Text] = useState('');
  const [input3text, setInput3Text] = useState('');

  return (
    <Box padding={8}>
      <Flex direction="column" gap={{ column: 6, row: 0 }}>
        <Flex direction="column" gap={{ column: 3, row: 0 }}>
          <Heading size="300">Small</Heading>
          <TextField
            helperText="Enter a title that captures the imagination of Pinners"
            id="field1"
            label="Email Address"
            onChange={({ value }) => {
              setInput1Text(value);
            }}
            placeholder="Enter your pin title"
            size="sm"
            type="text"
            value={input1text}
          />
        </Flex>

        <Flex direction="column" gap={{ column: 3, row: 0 }}>
          <Heading size="300">Medium</Heading>
          <TextField
            helperText="Enter a title that captures the imagination of Pinners"
            id="field2"
            label="Title"
            onChange={({ value }) => {
              setInput2Text(value);
            }}
            placeholder="Enter your pin title"
            size="md"
            type="text"
            value={input2text}
          />
        </Flex>
        <Flex direction="column" gap={{ column: 3, row: 0 }}>
          <Heading size="300">Large</Heading>
          <TextField
            helperText="Enter a title that captures the imagination of Pinners"
            id="field3"
            label="Title"
            onChange={({ value }) => {
              setInput3Text(value);
            }}
            placeholder="Enter your pin title"
            size="lg"
            type="text"
            value={input3text}
          />
        </Flex>
      </Flex>
    </Box>
  );
}

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.

TextArea
When users need to enter long amounts of text, use TextArea to ensure the full content will be shown.

NumberField
For numerical input, use NumberField. Exceptions: for telephone numbers, use <TextField type="tel" />. And for numerical input with possible leading 0's (e.g. ZIP codes), use <TextField type="text" />.

SearchField
If the input is used for searching content, use SearchField.