TextArea

TextArea allows for multi-line input.

Props

Component props
Name	Type	Default
`id` Required	`string`	-
	A unique identifier for the input.
`onChange` Required	`({\| event: SyntheticInputEvent<HTMLTextAreaElement>, value: string, \|}) => void`	-
	Callback triggered when the value of the input changes.
`disabled`	`boolean`	`false`
	Indicate if the input is currently 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. See the error message example for more details.
`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. See the helper text example for more details.
`label`	`string`	-
	The label for the input. Be sure to localize the text.
`name`	`string`	-
	A unique name for the input.
`onBlur`	`({\| event: SyntheticFocusEvent<HTMLTextAreaElement>, value: string, \|}) => void`	-
	Callback triggered when the user blurs the input.!
`onFocus`	`({\| event: SyntheticFocusEvent<HTMLTextAreaElement>, value: string, \|}) => void`	-
	Callback triggered when the user focuses the input.
`onKeyDown`	`({\| event: SyntheticKeyboardEvent<HTMLTextAreaElement>, 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 currently readOnly. See the readOnly example for more details.
`ref`	`React.Element<"input">`	-
	Ref that is forwarded to the underlying input element. See the ref example for more details.
`rows`	`number`	`3`
	Number of text rows to display. Note that tags take up more space, and will show fewer rows than specified.
`tags`	`$ReadOnlyArray<Element<typeof Tag>>`	-
	List of tags to display in the component. See the tags example for more details.
`value`	`string`	-
	The current value of the input.

Usage guidelines

When to use

Allowing users to input long portions of free-form text while ensuring all text entered remains visible.
Allowing users to type free-form options that get converted into Tags within the TextArea.

When not to use

For inputs that expect a certain format, like a date or email. Use a DatePicker or TextField instead.

Variants

Default

TextArea will expand to fill the width of the parent container by default.

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box width="100%">
      <TextArea
        id="aboutme"
        onChange={({value}) => setValue(value)}
        placeholder="Write something about yourself..."
        label="About me"
        value={value}
      />
    </Box>
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box width="100%">
      <TextArea
        id="aboutme"
        onChange={({value}) => setValue(value)}
        placeholder="Write something about yourself..."
        label="About me"
        value={value}
      />
    </Box>
  );
}

Helper text

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

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box width="100%">
      <TextArea
        id="aboutmemore"
        onChange={({value}) => setValue(value)}
        placeholder="Write something about yourself..."
        helperText="Describe your favorite hobbies, foods, or books."
        label="About me"
        value={value}
      />
    </Box>
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box width="100%">
      <TextArea
        id="aboutmemore"
        onChange={({value}) => setValue(value)}
        placeholder="Write something about yourself..."
        helperText="Describe your favorite hobbies, foods, or books."
        label="About me"
        value={value}
      />
    </Box>
  );
}

Read-only

TextArea can be in read-only mode in order to present information to the user without allowing them to edit the content. Typically this variation is used to show content or information that the user does not have permission or access to edit.

function Example(props) {
  const [value, setValue] = React.useState('To keep shopping inspirational and actionable, we set high standards for our Merchants. Your website was not approved due to fuzzy, low quality images.');
  return (
    <Box width="100%">
      <TextArea
        id="aboutmereadonly"
        onChange={({value}) => setValue(value)}
        label="Current errors"
        value={value}
        readOnly
      />
    </Box>
  );
}

function Example(props) {
  const [value, setValue] = React.useState('To keep shopping inspirational and actionable, we set high standards for our Merchants. Your website was not approved due to fuzzy, low quality images.');
  return (
    <Box width="100%">
      <TextArea
        id="aboutmereadonly"
        onChange={({value}) => setValue(value)}
        label="Current errors"
        value={value}
        readOnly
      />
    </Box>
  );
}

Disabled

TextArea can be disabled to indicate the user is unable to interact with it, either by mouse or keyboard. Disabled fields do not need to pass contrast requirements, so do not use a disabled TextArea to present information to the user (use readOnly instead).

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box width="100%">
      <TextArea
        disabled
        id="disabled"
        onChange={({value}) => setValue(value)}
        placeholder="Write something about yourself..."
        label="About me"
        value={value}
      />
    </Box>
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box width="100%">
      <TextArea
        disabled
        id="disabled"
        onChange={({value}) => setValue(value)}
        placeholder="Write something about yourself..."
        label="About me"
        value={value}
      />
    </Box>
  );
}

Error message

A TextArea can display its own error message.
To use our errors, simply pass in an errorMessage when there is an error present and we will handle the rest.

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box width="100%">
      <TextArea
        id="witherror"
        onChange={({value}) => setValue(value)}
        errorMessage={!value ? "This field can't be blank!" : null}
        placeholder="Write something about yourself..."
        label="About me"
        value={value}
      />
    </Box>
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box width="100%">
      <TextArea
        id="witherror"
        onChange={({value}) => setValue(value)}
        errorMessage={!value ? "This field can't be blank!" : null}
        placeholder="Write something about yourself..."
        label="About me"
        value={value}
      />
    </Box>
  );
}

With a ref

A TextArea with an anchor ref to a Popover component

function TextAreaPopoverExample() {
  const [open, setOpen] = React.useState(false);
  const anchorRef = React.useRef();
  return (
    <Box marginBottom={12} width="100%">
      <TextArea
        ref={anchorRef}
        label="Focus the TextArea 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 TextAreaPopoverExample() {
  const [open, setOpen] = React.useState(false);
  const anchorRef = React.useRef();
  return (
    <Box marginBottom={12} width="100%">
      <TextArea
        ref={anchorRef}
        label="Focus the TextArea 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>
  );
}

With tags

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

Note that the TextArea component 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.

function Example(props) {
  const [value, setValue] = React.useState('');
  const [tags, setTags] = React.useState(['San Francisco', 'New York']);
  const ref = React.useRef();

  const onChangeTagManagement = ({ value }) => {
    // Create new tags around new lines
    const tagInput = value.split(/\n+/);
    if (tagInput.length > 1) {
      setTags([
        ...tags,
        // Avoid creating a tag on content on the last line, 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)]);
    }
  }

  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 width="100%">
      <TextArea
        id="cities"
        label="Cities"
        ref={ref}
        onChange={onChangeTagManagement}
        onKeyDown={onKeyDownTagManagement}
        placeholder={value.length > 0 || tags.length > 0 ? '' : "Cities you've lived in"}
        tags={renderedTags}
        value={value}
      />
    </Box>
  );
}

function Example(props) {
  const [value, setValue] = React.useState('');
  const [tags, setTags] = React.useState(['San Francisco', 'New York']);
  const ref = React.useRef();

  const onChangeTagManagement = ({ value }) => {
    // Create new tags around new lines
    const tagInput = value.split(/\n+/);
    if (tagInput.length > 1) {
      setTags([
        ...tags,
        // Avoid creating a tag on content on the last line, 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)]);
    }
  }

  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 width="100%">
      <TextArea
        id="cities"
        label="Cities"
        ref={ref}
        onChange={onChangeTagManagement}
        onKeyDown={onKeyDownTagManagement}
        placeholder={value.length > 0 || tags.length > 0 ? '' : "Cities you've lived in"}
        tags={renderedTags}
        value={value}
      />
    </Box>
  );
}

Autofocus

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

Form submission

TextArea 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, TextArea 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 the TextArea
in a form and attach an onSubmit handler to that form.

Edit page on GitHub