TextAreaField

TextAreaField allows users to input multiline text content.

Demo

Usage

Import the TextAreaField component and styles and provide a label for accessibility/usability.

Comments

import { TextAreaField } from '@aws-amplify/ui-react';

export const DefaultTextAreaExample = () => {
  return (
    <TextAreaField label="Comments" defaultValue="Amplify UI is awesome!" />
  );
};

Accessibility

The form primitives are accessible by default. A matching label HTML element will be connected to the form control -- simply provide a label prop with a string or ReactNode. If no id is provided, one will be automatically generated and connected to both label and form control elements.

Resizeable

For a resizeable multiline field, use resize prop. Common values are horizontal, vertical, both. See MDN resize docs for supported values.

Address

Please enter a USPS validated address

import { TextAreaField } from '@aws-amplify/ui-react';

export const TextAreaResizableExample = () => {
  return (
    <TextAreaField
      label="Address"
      placeholder="1234 Main St."
      descriptiveText="Please enter a USPS validated address"
      resize="vertical"
    />
  );
};

Size

To change the general size, use the size prop. Available options are small, none (default), and large.

Small

Default

Large

import { Flex, TextAreaField } from '@aws-amplify/ui-react';

export const TextAreaSizeExample = () => {
  return (
    <Flex direction="column" gap="1.5rem">
      <TextAreaField
        label="Small"
        size="small"
        defaultValue="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
      />

      <TextAreaField
        label="Default"
        defaultValue="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
      />
      <TextAreaField
        label="Large"
        size="large"
        defaultValue="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
      />
    </Flex>
  );
};

Rows

To change the number of rows of text displayed, use the rows prop with desired number.

6 rows

import { TextAreaField } from '@aws-amplify/ui-react';

export const TextAreaRowsExample = () => {
  return (
    <TextAreaField
      label="6 rows"
      rows={6}
      defaultValue="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
    />
  );
};

Maximum length

To enforce a maximum length of multiline text, use the maxLength prop.

Maximum length of 100 characters

import { TextAreaField } from '@aws-amplify/ui-react';

export const TextAreaMaxLengthExample = () => {
  return (
    <TextAreaField
      label="Maximum length of 100 characters"
      defaultValue="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut laboree"
      maxLength={100}
    />
  );
};

Autoresize

You can add autoResize to have the textarea component resize based on the content in the input.

Note: this only works with a controlled TextAreaField

Comments

import * as React from 'react';
import { TextAreaField } from '@aws-amplify/ui-react';

export const AutoresizeTextareaExample = () => {
  const [value, setValue] = React.useState('');

  return (
    <TextAreaField
      autoResize
      label="Comments"
      value={value}
      onChange={(e) => {
        setValue(e.target.value);
      }}
    />
  );
};

Variations

There are two variation styles available: default and quiet.

Default

Quiet

import { TextAreaField } from '@aws-amplify/ui-react';

export const TextAreaFieldVariationExample = () => {
  return (
    <>
      <TextAreaField label="Default" />
      <TextAreaField label="Quiet" variation="quiet" />
    </>
  );
};

Descriptive text

To provide additional descriptive text of requirements of the field, use the descriptiveText field:

Address

Please enter a USPS validated address

import { Text, TextAreaField, View } from '@aws-amplify/ui-react';

export const TextAreaFieldDescriptiveExample = () => {
  return (
    <View width="100%">
      <TextAreaField
        label="Address"
        descriptiveText={
          <Text
            as="span"
            fontStyle="italic"
            fontSize="var(--amplify-font-sizes-small)"
          >
            Please enter a USPS validated address
          </Text>
        }
      />
    </View>
  );
};

States

The available TextAreaField states include isDisabled and isReadOnly. A disabled field will be not be focusable not mutable and will not be submitted with form data. A readonly field cannot be edited by the user.

Disabled

Readonly

You can't edit me!

import { Flex, TextAreaField } from '@aws-amplify/ui-react';

export const TextAreaFieldStatesExample = () => {
  return (
    <Flex direction="column" gap="1rem">
      <TextAreaField
        label="Disabled"
        defaultValue="Disabled"
        isDisabled={true}
      />
      <TextAreaField
        label="Readonly"
        defaultValue="You can't edit me!"
        isReadOnly={true}
      />
    </Flex>
  );
};

Required fields

Use the isRequired prop to specify a required field.

import { Button, Flex, TextAreaField } from '@aws-amplify/ui-react';

export const DefaultRequiredTextAreaFieldExample = () => {
  return (
    <Flex as="form" direction="column">
      <TextAreaField label="Essay question #1" isRequired={true} />
      <Button type="submit">Submit</Button>
    </Flex>
  );
};

There is no default styling for required fields. Customize the label or descriptiveText to instruct the form user of the required field.

import { Button, Flex, Text, TextAreaField } from '@aws-amplify/ui-react';

export const RequiredTextAreaFieldExample = () => {
  return (
    <Flex as="form" direction="column">
      <TextAreaField
        label={
          <Text>
            Essay Question #1
            <Text
              as="span"
              fontSize="var(--amplify-font-sizes-small)"
              color="var(--amplify-colors-font-error)"
            >
              {' '}
              (required)
            </Text>
          </Text>
        }
        isRequired={true}
      />
      <TextAreaField
        label="Essay Question #1"
        descriptiveText={
          <Text
            as="span"
            fontSize="var(--amplify-font-sizes-small)"
            color="var(--amplify-colors-font-error)"
            fontStyle="italic"
          >
            Required
          </Text>
        }
        isRequired={true}
      />
      <Button type="submit">Submit</Button>
    </Flex>
  );
};

Validation error styling

Use the hasError and errorMessage fields to mark a TextAreaField with a validation error.

Comments

Please enter a comment

import { Flex, TextAreaField } from '@aws-amplify/ui-react';

export const TextAreaFieldValidationErrorExample = () => {
  return (
    <Flex gap="1rem" direction="column">
      <TextAreaField
        label="Comments"
        hasError={true}
        errorMessage="Please enter a comment"
      />
    </Flex>
  );
};

CSS Styling

Theme

You can customize the appearance of all TextAreaField components in your application with a Theme.

TextAreaField Theme Source

Name

import { TextAreaField, ThemeProvider, Theme } from '@aws-amplify/ui-react';

const theme: Theme = {
  name: 'textareafield-theme',
  tokens: {
    components: {
      textareafield: {
        color: { value: '{colors.blue.90}' },
        _focus: {
          borderColor: { value: '{colors.blue.40}' },
        },
      },
    },
  },
};

export const TextAreaFieldThemeExample = () => (
  <ThemeProvider theme={theme} colorMode="light">
    <TextAreaField label="Name" defaultValue="Default Value" />
  </ThemeProvider>
);

Target classes

Class	Description
`amplify-textarea`	Class applied to the text area
`amplify-textareafield`	Top level element that wraps the TextAreaField primitive

--amplify-components-textareafield-border-color
--amplify-components-textareafield-color
--amplify-components-textareafield-focus-border-color

Global styling

To override styling on all TextAreaField primitives, you can set the Amplify CSS variables with the built-in .amplify-textareafield class.

Globally styled field

/* styles.css */
.amplify-textareafield {
  --amplify-components-fieldcontrol-border-color: rebeccapurple;
}

Local styling

To override styling on a specific TextAreaField, you can use a class selector or style props.

Using a class selector:

Square field

/* styles.css */
.custom-textareafield-class .amplify-textarea {
  border-radius: 0;
}

Using style props:

All style props will be applied to the Flex wrapper of the TextAreaField. To style the textarea of the TextAreaField, you can pass a inputStyles prop with the style props you want to apply to the input.

Address:

Special Field

import { Text, TextAreaField, useTheme } from '@aws-amplify/ui-react';

export const TextAreaFieldStylePropsExample = () => {
  const { tokens } = useTheme();
  return (
    <>
      <TextAreaField
        label={
          <Text
            fontWeight={tokens.fontWeights.bold}
            fontSize={tokens.fontSizes.xl}
          >
            Address:
          </Text>
        }
        padding="xl"
        border={`1px solid ${tokens.colors.primary[60]}`}
      />
      <TextAreaField
        label="Special Field"
        inputStyles={{
          backgroundColor: 'primary.10',
          border: `1px solid ${tokens.colors.primary[60]}`,
        }}
      />
    </>
  );
};