Textarea

A textarea is an interactive element that allows users to input and display multiple lines of text within a user interface.

Overview

pie-textarea is a Web Component built with Lit, providing users with a larger input space for writing and editing text that requires more than one line.

This component integrates easily with various frontend frameworks and can be customised through a set of properties.

Installation

To install pie-textarea in your application via npm or yarn:

npm i @justeattakeaway/pie-webc

yarn add @justeattakeaway/pie-webc

Props

Prop	Type	Description	Default
assistiveText	`string`	Allows assistive text to be displayed below the textarea. Must be provided if using a non-default status.	`undefined`
autocomplete	`string`	Allows the user to enable or disable autocomplete functionality on the input field. See MDN for more information and values.	`undefined`
autoFocus	`boolean`	If true, the textarea will be focused on the first render. No more than one element in the document or dialog may have the autofocus attribute. If applied to multiple elements the first one will receive focus. See MDN for more information.	`false`
defaultValue	`string`	During a form reset, the default value will replace the current value. This prop is not normally needed.	`undefined`
disabled	`boolean`	When true, the user cannot edit or interact with the control.	`false`
label	`string`	The label of the textarea field.	`""`
maxLength	`number`	Maximum length (number of characters) of value. To apply a length restriction, you must also provide label text.	`undefined`
name	`string`	The name of the textarea (used as a key/value pair with `value`). This is required in order to work properly with forms.	`undefined`
placeholder	`string`	The placeholder text to display when the textarea is empty.	`""`
readonly	`boolean`	When true, the user cannot edit the control. Not the same as disabled. See MDN for more information.	`false`
required	`boolean`	If true, the textarea is required to have a value before submitting the form. If there is no value, then the component validity state will be invalid. Important note: This will not prevent the form submission.	`false`
resize	`"auto"` `"manual"`	Controls the resizing behaviour of the textarea. When set to `auto`, the textarea will resize vertically as needed. When set to `manual`, the textarea will not resize automatically but can be resized by the user.	`"auto"`
size	`"small"` `"medium"` `"large"`	The size of the textarea field.	`"medium"`
status	`"default"` `"error"` `"success"`	The status of the textarea component / assistive text. If you use a non-default `status` you must also provide `assistiveText` for accessibility purposes.	`"default"`
value	`string`	The value of the textarea (used as a key/value pair in HTML forms with `name`).	`""`

Events

Event	Description
`change`	Fires when the textarea loses focus after the value has been changed.
`input`	Fires when the textarea value is changed.

Importing and usage in templates

For HTML and Vue:

// import as module into a js file that will be loaded on the page where the component is used.
import '@justeattakeaway/pie-webc/components/textarea.js';

<pie-textarea
    name="my-textarea"
    placeholder="Please enter a value"
    autocomplete="on"
    label="Label"
    maxLength="50"
    value=""
    autoFocus
    readonly>
</pie-textarea>

For React Applications:

import { PieTextarea } from '@justeattakeaway/pie-webc/react/textarea.js';

<PieTextarea
    name="my-textarea"
    placeholder="Please enter a value"
    autocomplete="on"
    label="Label"
    maxLength="50"
    value=""
    autoFocus
    readonly>
</PieTextarea>

// React templates (using Next 13 and SSR)
import { PieTextarea } from '@justeattakeaway/pie-textarea/dist/react';

<PieTextarea
    name="my-textarea"
    placeholder="Please enter a value"
    autocomplete="on"
    label="Label"
    maxLength="50"
    value=""
    autoFocus
    readonly>
</PieTextarea>

Forms usage

It is essential that when using the textarea inside the form, you provide a name attribute. HTML forms create key/value pairs for textarea data based on the name attribute, which is crucial for native form submission.

Validation

The textarea component utilizes the constraint validation API to provide a queryable validity state for consumers. This means that the component's validity can be checked via a validity getter.

Example:

const textarea = document.querySelector('pie-textarea');
console.log(textarea.validity.valid);

This getter can be useful for reducing the amount of validation code in your application. For example, if you want to create a textarea that requires attention, you can set the required property on the component. You can then check the validity of the input in your application code:

<pie-textarea
  id="my-textarea"
  required>
</pie-textarea>

const textarea = document.querySelector('pie-textarea');
const isValid = textarea.validity.valid;

// We could use this to drive the status and assistiveText properties on our textarea (this would likely be inside a submit event handler in a real application)
if (!isValid) {
  textarea.status = 'error';
  textarea.assistiveText = 'This textarea is required';
}

These concepts work just as well inside a Vue or React application.

Displaying error messages

As mentioned earlier, we suggest consumers disable native HTML validation using the novalidate attribute on the form element. This will prevent the browser from displaying its own validation messages, allowing you to control the validation experience for your users.

To display validation messages, you can use the assistiveText and status properties on the textarea component. The assistiveText property is used to display a message below the textarea, and the status property is used to set the visual state of the textarea. The status property can be set to error or success, or you can omit providing a status to display the assistiveText in a neutral state.

<pie-textarea
  name="details"
  assistiveText="Please provide more details"
  status="error">
</pie-textarea>

Displaying success messages works in the same way, but with the status property set to success.

<pie-textarea
  name="details"
  assistiveText="Please provide more details"
  status="success">
</pie-textarea>