Forma 36 - TextInput

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;


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>
  );
}
Open in Playground

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.


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>
  );
}
Open in Playground

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.

Using an icon

It is possible to pass an icon to the TextInput, it will be rendered on the left hand side of the input. Example of usage:


function TextInputIconExample() {
  return (
    <Stack flexDirection="column">
      <TextInput
        icon={<SearchIcon />}
        size="small"
        placeholder="Search for an item"
      />
      <TextInput
        icon={<SearchIcon />}
        size="medium"
        placeholder="Search for an item"
      />
    </Stack>
  );
}function TextInputIconExample() {
  return (
    <Stack flexDirection="column">
      <TextInput
        icon={<SearchIcon />}
        size="small"
        placeholder="Search for an item"
      />
      <TextInput
        icon={<SearchIcon />}
        size="medium"
        placeholder="Search for an item"
      />
    </Stack>
  );
}
Open in Playground

With different sizes

TextInput comes with the small and medium sizes. Example of usage:


function TextInputSizeExample() {
  return (
    <Stack flexDirection="column">
      <TextInput size="small" defaultValue="I'm a small TextInput" />
      <TextInput size="medium" defaultValue="I'm a medium TextInput" />
    </Stack>
  );
}function TextInputSizeExample() {
  return (
    <Stack flexDirection="column">
      <TextInput size="small" defaultValue="I'm a small TextInput" />
      <TextInput size="medium" defaultValue="I'm a medium TextInput" />
    </Stack>
  );
}
Open in Playground

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:


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>
  );
}
Open in Playground

Different states


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>
  );
}
Open in Playground

Props (API reference)

Open in Storybook

TextInput

Name	Type	Default
className	string CSS class to be appended to the root element
css	string number false true ComponentSelector Keyframes SerializedStyles ArrayInterpolation<undefined> ObjectInterpolation<undefined> (theme: any) => Interpolation<undefined>
defaultValue	string Set's default value for text input
icon	ReactElement<any, string \| JSXElementConstructor<any>> Expects any of the icon components
id	string Sets the id of the input
isDisabled	false true Applies disabled styles	false
isInvalid	false true Applies invalid styles	false
isReadOnly	false true Applies read-only styles	false
isRequired	false true Validate the input	false
name	string Set the name of the input
onBlur	FocusEventHandler<HTMLInputElement \| HTMLTextAreaElement> Allows to listen to an event when an element loses focus
onChange	ChangeEventHandler<HTMLInputElement \| HTMLTextAreaElement> Allows to listen to an input’s change in value
onFocus	FocusEventHandler<HTMLInputElement \| HTMLTextAreaElement> Allows to listen to an event when an element get focused
onKeyDown	KeyboardEventHandler<HTMLInputElement \| HTMLTextAreaElement> Allows to listen to an event when a key is pressed
size	"small" "medium" Defines which size of the input should be rendered	medium
testId	string A [data-test-id] attribute used for testing purposes	cf-ui-text-input
value	string Set the value of the input
willBlurOnEsc	false true Boolean property that allows to blur on escape	true

TextInput.Group

Name	Type	Default
children required	ReactNode
className	string CSS class to be appended to the root element
spacing	"spacing2Xs" "spacingXs" "spacingS" "spacingM" "spacingL" "spacingXl" "spacing2Xl" "spacing3Xl" "spacing4Xl" "none" Sets the spacing of the elements if variant is separate.	spacingS
testId	string A [data-test-id] attribute used for testing purposes

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.