TextArea

Importing

import { TextArea } from '@customerio/pluma-components/react';

Usage

<TextArea value="Foo" ariaLabel="React demo input" />

Events

The PlumaTextArea component accepts the following functions, corresponding to native events on the input element:

• onChange
• onInput
• onFocus
• onBlur

Note: The onChange function is not the idiomatic React onChange callback (which acts more like the native input event). To keep the component API consistent between frameworks, we expose event handlers that correspond to the browser native event. This means that TextAreas onChange only fires after a blur, for example (rather than while typing).

import { TextArea } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
	const [value, setValue] = useState('Foo');

	return <TextArea
		ariaLabel="Event demo input"
		value={value}
		onChange={(e) => {
			console.log('onChange fired');
			setValue(e.target.value);
		}}
		onInput={(e) => {
			console.log('onInput fired');
			setValue(e.target.value);
		}}
		onFocus={() => console.log('onFocus fired')}
		onBlur={() => console.log('onBlur fired')}
	/>
}

Labels and descriptions

A PlumaTextArea component should always be associated with a label. The component accepts a label string prop, which will render the text above the input:

<TextArea
	label="First name"
/>

Alternatively, the ariaLabelledby prop can be used to associate the input with a label element elsewhere in the DOM. It is also recommended to add a for attribute on the custom label, along with an id attribute on the input, to ensure the label is properly associated with the input.

<Box
	as="label"
	id="my_label_id"
	htmlFor="my_input"
>
	First name
</Box>
<TextArea
	id="my_input"
	ariaLabelledby="my_label_id"
/>

Finally, the ariaLabel prop can be used if no other element is suitable for a label.

Additionally, a hint text can be added below the input with the description prop:

<TextArea
	label="Username"
	description="Your username can be changed at any time"
/>

Errors

The PlumaTextArea component accepts an isInvalid prop, which will render the input in an error state:

<TextArea
	label="Comment"
	isInvalid={true}
/>

It is also highly recommended to provide an error message when the input is invalid. This will render below the input:

<TextArea
	label="Comment"
	isInvalid={true}
	error="Please enter a valid comment"
/>

Form submission behavior

By default, pressing Enter in a textarea creates a new line. However, with the shouldSubmitOnEnter prop set to true, pressing Enter will submit the form instead of creating a new line. Users can still add a new line by pressing Shift+Enter.

<Form onSubmit={(e) => {
	  e.preventDefault();
	  alert('Form submitted!');
	}}
>
	<FormLayout>
		<TextArea
			label="Comment (press Enter to submit)"
			shouldSubmitOnEnter={true}
		/>
		<ButtonGroup>
			<Button type="submit">Submit</Button>
		</ButtonGroup>
  	</FormLayout>
</Form>

Password manager autofill

By default, PlumaTextArea disables password manager autofill to prevent unwanted interference. This behavior can be controlled with the shouldAllowAutofill prop.

When to use:

• Keep shouldAllowAutofill={false} (default) for general text areas where password managers often interfere inappropriately
• Set shouldAllowAutofill={true} only if you specifically want password managers to function in this textarea (rare for textareas)

When shouldAllowAutofill is false, the component adds attributes to disable common password managers (1Password, LastPass, Bitwarden, Dashlane) and sets autocomplete="off".

import { TextArea } from '@customerio/pluma-components/react';

export default function Example() {
  return <>
    <TextArea
      label="API Response"
      description="Password managers disabled (default)"
    />

    <TextArea
      mt="200"
      label="Notes"
      shouldAllowAutofill={true}
      description="Password managers enabled"
    />
  </>
}

Auto-growing text area

The PlumaTextArea component supports auto-growing height based on content with the minRows and maxRows props.

<TextArea
	label="Auto-growing (2-6 rows)"
	minRows={2}
	maxRows={6}
	placeholder="Type multiple lines to see auto-grow in action..."
/>

• minRows sets the minimum number of visible rows when empty
• maxRows sets the maximum number of rows before scrolling
• When both are set, the textarea automatically grows and shrinks based on content
• When auto-growing is enabled, manual resizing is disabled

Resizing and width

By default, PlumaTextArea renders at full width and can be resized vertically (but not horizontally).

Note: In the code snippet examples above, the component is placed in a 300px wide container. Below is a full width example without the constraint:

<TextArea
	label="Full width"
/>

When rendered at full width, it cannot be resized horizontally (it always stretches to fill the container).

To allow horizontal resizing, isFullWidth must be set to false. Additionally, resize should be set to horizontal or both:

<TextArea
	label="Resizable"
  	isFullWidth={false}
  	resize="both"
/>

Customizing labels

If a string label is not sufficient, a component can be used to render the label.

import { TextArea, Icon } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
  const [value, setValue] = useState('');

  return <TextArea
    label={<>Custom label <Icon name="campaigns" isInline={true} size="sm" /></>}
    value={value}
    onInput={(e) => {
      setValue(e.target.value);
    }}
  />
}

Customizing descriptions

If a string description is not sufficient, a component can be used to render the description.

import { TextArea, Link } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
  const [value, setValue] = useState('');

  return <TextArea
    ariaLabel="Custom description input"
    description={<>Custom description, <Link href="https://docs.customer.io" isExternal={true} variant="secondary">see docs for details</Link></>}
    value={value}
    onInput={(e) => {
      setValue(e.target.value);
    }}
  />
}

Customizing errors

If a string error is not sufficient, a component can be used to render the error.

import { TextArea, Link } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
  const [value, setValue] = useState('');

  return <TextArea
    ariaLabel="Custom error input"
    error={<>Custom error, <Link href="https://docs.customer.io" isExternal={true} variant="secondary">see docs for help</Link></>}
    value={value}
    onInput={(e) => {
      setValue(e.target.value);
    }}
  />
}