TextArea

A text area allows a user to enter text with a keyboard into a multi-line input form element.

Uncontrolled Value

By default, the TextArea component handles its value uncontrolled. In the uncontrolled variant you can pass in a defaultValue to set a value by default.

<TextArea
  label="Description"
  defaultValue="Convergo is an accessible design system."
/>

<TextArea
  label="Description"
  defaultValue="Convergo is an accessible design system."
/>

<TextArea
  label="Description"
  defaultValue="Convergo is an accessible design system."
/>

Controlled Value

You can also handle the value of the component in a controlled manner. To do so, you can pass in a value prop as well as an onChange handler to modify the value when the user types.

function Example() {
  const [value, setValue] = useState(
    'Convergo is an accessible design system.'
  );

  return (
    <div>
      <TextArea
        label="Description"
        value={value}
        onChange={setValue}
      />

      <div>Value: {value}</div>
    </div>
  );
}

function Example() {
  const [value, setValue] = useState(
    'Convergo is an accessible design system.'
  );

  return (
    <div>
      <TextArea
        label="Description"
        value={value}
        onChange={setValue}
      />

      <div>Value: {value}</div>
    </div>
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState(
    'Convergo is an accessible design system.'
  );

  return (
    <div>
      <TextArea
        label="Description"
        value={value}
        onChange={setValue}
      />

      <div>
        Value: {value}
      </div>
    </div>
  );
}

Labeling

A TextArea component should be labeled with a visual text through the label prop. If the TextArea does not include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

<TextArea label='Description' />

<TextArea label='Description' />

<TextArea label="Description" />

Label Alignment

For languages that are read left-to-right (LTR), such as English, the label of the TextArea component is displayed on the left side of the input. For right-to-left (RTL) languages, such as Arabic, this is flipped. You can control the position of the label through the labelPlacement prop.

<TextArea label='Description' labelPlacement='top end' />

<TextArea label='Description' labelPlacement='top end' />

<TextArea
  label="Description"
  labelPlacement="top end"
/>

Label Position

By default, the label of the TextArea component is displayed above the input. With the labelPlacement prop this placement can be adjusted to be on the side of the input.

<TextArea label='Description' labelPlacement='side end' />

<TextArea label='Description' labelPlacement='side end' />

<TextArea
  label="Description"
  labelPlacement="side end"
/>

Required

To indicate to the user that the TextArea is required you can use the isRequired prop.

<TextArea label='Description' isRequired />

<TextArea label='Description' isRequired />

<TextArea
  label="Description"
  isRequired
/>

Validation

The TextArea component has built-in accessible validation support. To indicate whether the field is valid or not you can use the errorMessage prop.

function Example() {
  const [value, setValue] = useState(
    'Convergo is an accessible design system.'
  );

  // Only allow alphanumeric characters, so e.g. the dot character is forbidden.
  const alphanumericRegExp = /^[a-zA-Z0-9 ]*$/;
  const isValidAlphanumericValue = alphanumericRegExp.test(value);

  return (
    <TextArea
      label="Description"
      value={value}
      onChange={setValue}
      errorMessage={!isValidAlphanumericValue &&
        'This field needs to be alphanumeric.'}
    />
  );
}

function Example() {
  const [value, setValue] = useState(
    'Convergo is an accessible design system.'
  );

  // Only allow alphanumeric characters, so e.g. the dot character is forbidden.
  const alphanumericRegExp = /^[a-zA-Z0-9 ]*$/;
  const isValidAlphanumericValue = alphanumericRegExp.test(
    value
  );

  return (
    <TextArea
      label="Description"
      value={value}
      onChange={setValue}
      errorMessage={!isValidAlphanumericValue &&
        'This field needs to be alphanumeric.'}
    />
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState(
    'Convergo is an accessible design system.'
  );

  // Only allow alphanumeric characters, so e.g. the dot character is forbidden.
  const alphanumericRegExp =
    /^[a-zA-Z0-9 ]*$/;
  const isValidAlphanumericValue =
    alphanumericRegExp
      .test(value);

  return (
    <TextArea
      label="Description"
      value={value}
      onChange={setValue}
      errorMessage={!isValidAlphanumericValue &&
        'This field needs to be alphanumeric.'}
    />
  );
}

Description

To give further instructions or more verbose examples to the user about a TextArea you can provide a description prop. Avoid using error like tone of voice of the message. If an errorMessage prop is provided it will replace the description.

<TextArea
  label="Description"
  description="An enumeration of the essential qualities of a thing or species"
/>

<TextArea
  label="Description"
  description="An enumeration of the essential qualities of a thing or species"
/>

<TextArea
  label="Description"
  description="An enumeration of the essential qualities of a thing or species"
/>

Placeholder

To give further instructions or examples to the user about a TextArea you can provide a placeholder prop.

<TextArea label="Description" placeholder="Please enter a description." />

<TextArea
  label="Description"
  placeholder="Please enter a description."
/>

<TextArea
  label="Description"
  placeholder="Please enter a description."
/>

Contextual Help

To offer the user contextual help, the TextArea supports passing a contextualHelp prop, that accepts a ReactNode.

<TextArea 
  label='Description' 
  contextualHelp={(
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        </Text>
      </Content>
    </ContextualHelp>
  )} 
/>

<TextArea
  label="Description"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur
          adipiscing elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

<TextArea
  label="Description"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>
          Lorem Ipsum
        </Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum
          dolor sit
          amet,
          consectetur
          adipiscing
          elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

Disabled

The TextArea component can be disabled via the isDisabled prop.

<TextArea
  label="Description"
  defaultValue="Convergo is an accessible design system."
  isDisabled
/>

<TextArea
  label="Description"
  defaultValue="Convergo is an accessible design system."
  isDisabled
/>

<TextArea
  label="Description"
  defaultValue="Convergo is an accessible design system."
  isDisabled
/>

Read Only

The TextArea component can be marked as read only via the isReadOnly prop.

<TextArea
  label="Description"
  defaultValue="Convergo is an accessible design system."
  isReadOnly
/>

<TextArea
  label="Description"
  defaultValue="Convergo is an accessible design system."
  isReadOnly
/>

<TextArea
  label="Description"
  defaultValue="Convergo is an accessible design system."
  isReadOnly
/>

Accessibility

In order to support internationalization, provide a localized string to the label or aria-label prop.

API