Textarea

The <nys-textarea> is a reusable web component for use in New York State digital products. It allows users to input multiple lines of text to be collected.

Options

Rows

The rows attribute specifies the visible height of a text area, in number of lines.

The default value is 4

<nys-textarea label="This textarea renders with 6 rows" rows="6"></nys-textarea>

Width

If no width is provided, the <nys-textarea> will default to full. Supported widths are sm, md, lg, and full. Setting property width="full" will take up the full width of the parent container.

If an invalid option is assigned to width, it will be ignored and default to width="full"

<nys-textarea width="md" label="This textarea is md"></nys-textarea>

Resize Behavior

By default a user can resize the <nys-textarea> vertically. If you want to disallow resizing altogether add resize="none".

Note: resize is not affected by setting <nys-textarea> to disabled or readonly as they are independent.

<nys-textarea label="This textarea is not resizable" resize="none"></nys-textarea>

Description

You can include a description to provide additional context for the user. This is useful for providing instructions or clarifying the input. You can include a description as a property or slot it into the element.

<nys-textarea label="Label" description="description property"></nys-textarea>
<nys-textarea label="Label">
  <p slot="description">Description slot 
    <a href="https://ny.gov">providing more options</a>
  </p>
</nys-textarea>

Placeholder

<nys-textarea label="Placeholder" placeholder="this is a placeholder"></nys-textarea>

Disabled

<nys-textarea label="Disabled textarea" disabled></nys-textarea>

Readonly

<nys-textarea readonly label="Readonly textarea" value="This text cannot be changed"></nys-textarea>

Max length

<nys-textarea maxlength="10" label="Max Length" description="You cannot type more than 10 characters in the below field"></nys-textarea>

Required

<nys-textarea required label="Required textarea"></nys-textarea>

Optional

<nys-textarea optional label="Optional textarea"></nys-textarea>

Error Message

To display an error message, pass in the showError property to the <nys-textarea> component. Setting errorMessage does not display the message without showError set to true.

<nys-textarea showError errorMessage="You did not provide a value for this field." label="Describe the incident" ></nys-textarea>

Usage

When to use this component

• To collect multiple lines of text input from the user (e.g., comments, descriptions).
• For open-ended input specific to the user (e.g., personal notes, feedback).

When to consider something else

• If you need to collect a single line of text input, use an input field instead.
• If the input should be selected from predefined options, use a dropdown or radio button.

Accessibility

The <nys-textarea> component includes the following accessibility-focused features:

• Proper ARIA roles and attributes to ensure screen readers can interpret the label correctly.
• Keyboard navigation support, allowing users to tab into the input using the keyboard.
• Visual focus indicators to help users navigate the component.
• Include a label property to provide accessible text for screen readers.

Properties

CSS Variables

Events

The <nys-textarea> component emits four custom Javascript events:

1. nys-input – Fired when the textarea state changes.
2. nys-focus – Fired when the textarea gains focus.
3. nys-blur – Fired when the textarea loses focus.
4. nys-select – Fired when the user selects text within the textarea.

You can listen to these events using JavaScript:

// Select the textarea component
const textarea = document.querySelector('nys-textarea');
// Listen for the 'nys-input' event
textarea.addEventListener('nys-input', (event) => {
  console.log('Text input changed:', event.detail.value);
});