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.
`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.

Example

A TextArea will expand to fill the width of the parent container.

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

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

Example: Disabled

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

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

Example: 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 padding={2} color="white">
      <TextArea
        id="aboutmemore"
        onChange={({value}) => setValue(value)}
        placeholder="Write something about yourself..."
        helperText="I love to sail, run and visit remote places"
        label="With a placeholder"
        value={value}
      />
    </Box>
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box padding={2} color="white">
      <TextArea
        id="aboutmemore"
        onChange={({value}) => setValue(value)}
        placeholder="Write something about yourself..."
        helperText="I love to sail, run and visit remote places"
        label="With a placeholder"
        value={value}
      />
    </Box>
  );
}

Example: 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 (
    <TextArea
      id="witherror"
      onChange={({value}) => setValue(value)}
      errorMessage={!value ? "This field can't be blank!" : null}
      placeholder="Write something about yourself..."
      label="With an error message"
      value={value}
    />
  );
}

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

Example: 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}>
      <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}>
      <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>
  );
}

Example: 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 (
    <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}
    />
  );
}

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 (
    <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}
    />
  );
}

Autofocus

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

onSubmit

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