TextInput

TextInput is a form component, that allows users to input text or numbers and should be used in a form context.

TextInput is supporting different types of inputs, like text, email, file, number, password, search, url, where text is the default.

Import

import { TextInput } from '@contentful/f36-components';
// or
import { TextInput } from '@contentful/f36-forms';

Examples

Using as a controlled input

Controlled components in React are those in which form data is handled by the component’s state.

For using the TextInput as a controlled input, you need to:

• Pass value property, with this property it will already be a controlled component;
• Pass onChange handler, so you can use it to update the value of the input;

Open in Playground
function TextInputControlledExample() {
  const [value, setValue] = useState('your-email@domain.com');
  return (
    <FormControl isRequired isInvalid={!value}>
      <FormControl.Label>Email</FormControl.Label>
      <TextInput
        value={value}
        type="email"
        name="email"
        placeholder="your-email@domain.com"
        onChange={(e) => setValue(e.target.value)}
      />
      <FormControl.HelpText>Provide your email address</FormControl.HelpText>
      {!value && (
        <FormControl.ValidationMessage>
          Please, provide your email
        </FormControl.ValidationMessage>
      )}
    </FormControl>
  );
}
function TextInputControlledExample() {
  const [value, setValue] = useState('your-email@domain.com');
  return (
    <FormControl isRequired isInvalid={!value}>
      <FormControl.Label>Email</FormControl.Label>
      <TextInput
        value={value}
        type="email"
        name="email"
        placeholder="your-email@domain.com"
        onChange={(e) => setValue(e.target.value)}
      />
      <FormControl.HelpText>Provide your email address</FormControl.HelpText>
      {!value && (
        <FormControl.ValidationMessage>
          Please, provide your email
        </FormControl.ValidationMessage>
      )}
    </FormControl>
  );
}
Hide source

Using as an uncontrolled input

Uncontrolled components are those for which the form data is handled by the DOM itself. “Uncontrolled” refers to the fact that these components are not controlled by React state.

You can use the TextInput as an uncontrolled input, for that you can:

• Set the defaultValue property, it will ensure that the initial value of the input is set.
• Don't set the value as it will make the input controlled.

Open in Playground
function TextInputUncontrolledExample() {
  return (
    <FormControl isRequired>
      <FormControl.Label>Email</FormControl.Label>
      <TextInput
        defaultValue=""
        name="email"
        type="email"
        placeholder="your-email@domain.com"
      />
      <FormControl.HelpText>Provide your email address</FormControl.HelpText>
    </FormControl>
  );
}
function TextInputUncontrolledExample() {
  return (
    <FormControl isRequired>
      <FormControl.Label>Email</FormControl.Label>
      <TextInput
        defaultValue=""
        name="email"
        type="email"
        placeholder="your-email@domain.com"
      />
      <FormControl.HelpText>Provide your email address</FormControl.HelpText>
    </FormControl>
  );
}
Hide source

Using outside of forms

When TextInput is used outside of form (without FormControl) and has no <label> associated with it, you need to specify aria-label.

With action buttons

TextInput.Group enables the user to set a button at the start or end of an input, with some spacing or collapsed. Example of usage:

Open in Playground
function TextInputGroupExample() {
  const [isFirstLocked, setFirstLocked] = useState(true);
  const [isSecondLocked, setSecondLocked] = useState(true);
  return (
    <Stack flexDirection="column">
      <TextInput.Group>
        <TextInput
          aria-label="Content type name"
          id="content-type-name"
          defaultValue="blog"
          isDisabled={isFirstLocked}
        />
        <IconButton
          variant="secondary"
          icon={<LockIcon />}
          onClick={() => {
            setFirstLocked((value) => !value);
          }}
          aria-label="Unlock"
        />
      </TextInput.Group>
      <TextInput.Group spacing="spacingS">
        <TextInput
          aria-label="Content type name"
          id="content-type-name-2"
          defaultValue="blog"
          isDisabled={isSecondLocked}
        />
        <IconButton
          variant="secondary"
          icon={<LockIcon />}
          onClick={() => {
            setSecondLocked((value) => !value);
          }}
          aria-label="Unlock"
        />
      </TextInput.Group>
    </Stack>
  );
}
function TextInputGroupExample() {
  const [isFirstLocked, setFirstLocked] = useState(true);
  const [isSecondLocked, setSecondLocked] = useState(true);
  return (
    <Stack flexDirection="column">
      <TextInput.Group>
        <TextInput
          aria-label="Content type name"
          id="content-type-name"
          defaultValue="blog"
          isDisabled={isFirstLocked}
        />
        <IconButton
          variant="secondary"
          icon={<LockIcon />}
          onClick={() => {
            setFirstLocked((value) => !value);
          }}
          aria-label="Unlock"
        />
      </TextInput.Group>
      <TextInput.Group spacing="spacingS">
        <TextInput
          aria-label="Content type name"
          id="content-type-name-2"
          defaultValue="blog"
          isDisabled={isSecondLocked}
        />
        <IconButton
          variant="secondary"
          icon={<LockIcon />}
          onClick={() => {
            setSecondLocked((value) => !value);
          }}
          aria-label="Unlock"
        />
      </TextInput.Group>
    </Stack>
  );
}
Hide source

Different states

Open in Playground
function TextInputStatesExample() {
  return (
    <Stack flexDirection="column">
      <TextInput
        defaultValue="I'm disabled TextInput"
        isDisabled
        name="value-1"
      />
      <TextInput
        defaultValue="I'm invalid TextInput"
        isInvalid
        name="value-1"
      />
      <TextInput
        defaultValue="I'm read-only TextInput"
        isReadOnly
        name="value-1"
      />
    </Stack>
  );
}
function TextInputStatesExample() {
  return (
    <Stack flexDirection="column">
      <TextInput
        defaultValue="I'm disabled TextInput"
        isDisabled
        name="value-1"
      />
      <TextInput
        defaultValue="I'm invalid TextInput"
        isInvalid
        name="value-1"
      />
      <TextInput
        defaultValue="I'm read-only TextInput"
        isReadOnly
        name="value-1"
      />
    </Stack>
  );
}
Hide source

Props (API reference)

TextInput

• Name

  className

  Description

  CSS class to be appended to the root element

  string
• Name

  defaultValue

  Description

  Set's default value for text input

  string
• Name

  icon

  Description

  Expects any of the icon components

  ReactElement<any, string | JSXElementConstructor<any>>
• Name

  id

  Description

  Sets the id of the input

  string
• Name

  isDisabled

  Description

  Applies disabled styles

  false

  true
• Name

  isInvalid

  Description

  Applies invalid styles

  false

  true
• Name

  isReadOnly

  Description

  Applies read-only styles

  false

  true
• Name

  isRequired

  Description

  Validate the input

  false

  true
• Name

  name

  Description

  Set the name of the input

  string
• Name

  onBlur

  Description

  Allows to listen to an event when an element loses focus

  FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>
• Name

  onChange

  Description

  Allows to listen to an input’s change in value

  ChangeEventHandler<HTMLInputElement | HTMLTextAreaElement>
• Name

  onFocus

  Description

  Allows to listen to an event when an element get focused

  FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>
• Name

  onKeyDown

  Description

  Allows to listen to an event when a key is pressed

  KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>
• Name

  size

  Description

  Defines which size of the input should be rendered

  "small"

  "medium"

  Default

  medium
• Name

  testId

  Description

  A [data-test-id] attribute used for testing purposes

  string

  Default

  cf-ui-text-input
• Name

  type

  Description

  Set the type of the input

  "number"

  "text"

  "email"

  "file"

  "password"

  "search"

  "url"
• Name

  value

  Description

  Set the value of the input

  string
• Name

  willBlurOnEsc

  Description

  Boolean property that allows to blur on escape

  false

  true

TextInput.Group

• Name

  children(required)

  ReactNode
• Name

  className

  Description

  CSS class to be appended to the root element

  string
• Name

  spacing

  Description

  Sets the spacing of the elements if variant is separate.

  "spacing2Xs"

  "spacingXs"

  "spacingS"

  "spacingM"

  "spacingL"

  "spacingXl"

  "spacing2Xl"

  "spacing3Xl"

  "spacing4Xl"

  "none"
• Name

  testId

  Description

  A [data-test-id] attribute used for testing purposes

  string

Content guidelines

• Use direct and succinct copy that helps a user to successfully complete a form
• Do not preface the instructions with introductory text, such as "please"
• Use sentence style caps (in which only the first word of a sentence or term is capitalized)

Accessibility

• To ensure TextInput meets accessibility standards, provide name and id
• Keep in mind that to provide that accessible inputs, you need to use labels.
• If you decide, that for some reason you would not use the label, please provide aria-label attribute to make it accessible for technologies like screen readers.