@justeattakeaway/pie-textarea v0.16.5

@justeattakeaway/pie-textarea

Source Code | Design Documentation | NPM

@justeattakeaway/pie-textarea is a Web Component built using the Lit library. It offers a simple and accessible textarea component for web applications.

Table of Contents

• Installation
• Documentation
  • Properties
  • Slots
  • CSS Variables
  • Events
• Forms Usage
  • Validation
    • Example
    • Displaying error messages
• Usage Examples
• Questions and Support
• Contributing

Installation

To install any of our web components in your application, we would suggest following the getting started guide to set up your project.

Ideally, you should install the component using the @justeattakeaway/pie-webc package, which includes all of the components. Or you can install the individual component package.

Documentation

Properties

Slots

This component does not have any slots. All content is controlled through properties.

CSS Variables

This component does not expose any CSS variables for style overrides.

Events

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.

Using the constraint validation API we provide is completely optional. Feel free to use whatever form of validation best suits your application's needs. The validity state of a textarea will not interfere with the form submission or page behaviour.

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>

Usage Examples

For HTML:

// import as module into a js file e.g. main.js
import '@justeattakeaway/pie-webc/components/textarea.js';

<pie-textarea
    name="my-textarea"
    placeholder="Please enter a value"
    autocomplete="on"
    value=""
    autoFocus
    readonly>
</pie-textarea>
<script type="module" src="/main.js"></script>

For Native JS Applications, Vue, Angular, Svelte etc.:

// Vue templates (using Nuxt 3)
import '@justeattakeaway/pie-webc/components/textarea.js';

<pie-textarea
    name="my-textarea"
    placeholder="Please enter a value"
    autocomplete="on"
    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"
    value=""
    autoFocus
    readonly>
</PieTextarea>

Questions and Support

If you work at Just Eat Takeaway.com, please contact us on #help-designsystem. Otherwise, please raise an issue on Github.

Contributing

Check out our contributing guide for more information on local development and how to run specific component tests.