@dev.mohe/mwc-textarea v0.19.3

<mwc-textarea>

IMPORTANT: The Material Web Components are a work in progress and subject to major changes until 1.0 release.

Text areas let users enter and edit text.

Material Design Guidelines: text areas

Demo

Installation

npm install @dev.mohe/mwc-textarea

NOTE: The Material Web Components are distributed as ES2017 JavaScript Modules, and use the Custom Elements API. They are compatible with all modern browsers including Chrome, Firefox, Safari, Edge, and IE11, but an additional tooling step is required to resolve bare module specifiers, as well as transpilation and polyfills for IE11. See here for detailed instructions.

Example usage

Standard

<mwc-textarea label="My Textarea"></mwc-textarea>

<script type="module">
  import '@dev.mohe/mwc-textarea';
</script>

Helper Text

<mwc-textarea label="My Textarea" helper="Helper Text"></mwc-textarea>

Primary Color

<style>
  mwc-textarea {
    --mdc-theme-primary: green;
  }
</style>

<mwc-textarea
    label="My Textarea"
    required>
</mwc-textarea>

Variants

Outlined

<mwc-textarea
    outlined
    label="My Textarea">
</mwc-textarea>

Shaped

<style>
  mwc-textarea.rounded {
    --mdc-shape-small: 28px;
  }
</style>

<mwc-textarea
    class="rounded"
    label="My Textarea"
    outlined>
</mwc-textarea>

API

Properties/Attributes

* TextFieldType is exported by mwc-textarea and mwc-textarea-base.

type TextFieldType = 'text'|'search'|'tel'|'url'|'email'|'password'|
    'date'|'month'|'week'|'time'|'datetime-local'|'number'|'color';

** TextAreaCharCounter is exported by mwc-textarea.

type TextAreaCharCounter = 'external'|'internal';

\*\*\* `ValidityTransform` is not exported. See the [validation section](#Validation) for more details.
```ts
type ValidityTransform = (value: string, nativeValidity: ValidityState) => Partial<ValidityState>

*** The name property should only be used for browser autofill as webcomponent form participation does not currently consider the name attribute. See #289.

Methods

CSS Custom Properties

Inherits CSS Custom properties from:

• mwc-ripple
• mwc-notched-outline.
• mwc-icon

Global Custom Properties

This component exposes the following global theming custom properties.

Validation

<mwc-textarea> follows the basic <input> constraint validation model. It exposes:

• required
• maxLength
• validity
• willValidate
• checkValidity()
• reportValidity()
• setCustomValidity(message)

Additionally, it implements more features such as:

• validationMessage
• validateOnInitialRender
• and validityTransform

By default, <mwc-textarea> will report validation on blur.

Custom validation logic

The validityTransform property is a function that can be set on <mwc-textarea> to implement custom validation logic that transforms the ValidityState of the input control. The type of a ValidityTransform is the following:

(value: string, nativeValidity: ValidityState) => Partial<ValidityState>

Where value is the new value in the textarea to be validated and nativeValidity is an interface of ValidityState of the native input control. For example:

<mwc-textarea
    id="my-textarea"
    maxlength="5"
    value="doggos">
</mwc-textarea>
<script>
  const textarea = document.querySelector('#my-textarea');
  textarea.validityTransform = (newValue, nativeValidity) => {
    if (!nativeValidity.valid) {
      if (nativeValidity.tooLong) {
        const hasDog = newValue.includes('dog');
        // changes to make to the nativeValidity
        return {
          valid: hasDog,
          tooLong: !hasDog;
        };
      } else {
        // no changes
        return {};
      }
    } else {
      const isValid = someExpensiveOperation(newValue);
      // changes to make to the native validity
      return {
        valid: isValid,
        // or whatever type of ValidityState prop you would like to set (if any)
        customError: !isValid,
      };
    }
  }
</script>

In this example we first check the native validity which is invalid due to the maxlength (the value is doggos which is a string longer than 5). The value includes dog, thus we make it valid and undo the tooLong error in the ValidityState by returning a Partial<ValidityState> that indicates what to change in the initial validity.

In this example, we also skip an expensive validity check by short-circuiting the validation by checking the native validation.

Note: the UI will only update as valid / invalid by checking the valid property of the transformed ValidityState.

Additional references

• MDC Web textfields