FormElementMixin

Allows a component to participate in HTML form submission
OVERVIEW | USAGE | API

Overview

Purpose: allows a component to participate in HTML form submission. This lets you use a custom element in an HTML form the same way you would a standard input, textarea, etc.

This mixin works in the middle of the Elix render pipeline:

events → methods → setState ➞ render DOM → post-render

Expects the component to provide:

  • setState method, usually supplied by ReactiveMixin.
  • value property that exposes a string that should be submitted as the value for this element.

Provides the component with:

  • valid state member. By default this is true, but the component can set it to false to indicate the field is currently invalid and cannot be submitted.
  • validationMessage state member. This is a string that can be set to a validation error message if the field is currently invalid.
  • form, name, type properties that behave the same as the standard HTML properties with the same corresponding names.

Usage

import FormElementMixin from "elix/src/base/FormElementMixin.js";
import ReactiveElement from "elix/define/ReactiveElement.js";
class MyElement extends FormElementMixin(ReactiveElement) {}

Example

The form below contains custom elements whose values will be submitted with the form.

Your browser does not support form-associated custom elements. As of September 2019, form features are only available in Chrome and Edge development builds.

Form submission results:

Demo: FormElementMixin lets these custom elements participate in a form ⇲

API

Used by classes AutoCompleteComboBox, AutoCompleteInput, AutoSizeTextarea, CalendarMonthNavigator, ComboBox, DateComboBox, DateInput, DropdownList, FilterComboBox, FilterListBox, Input, ListBox, ListComboBox, NumberSpinBox, OptionList, PlainAutoCompleteComboBox, PlainAutoCompleteInput, PlainAutoSizeTextarea, PlainCalendarMonthNavigator, PlainComboBox, PlainDateComboBox, PlainDateInput, PlainDropdownList, PlainFilterComboBox, PlainFilterListBox, PlainInput, PlainListBox, PlainListComboBox, PlainNumberSpinBox, PlainOptionList, PlainSpinBox, and SpinBox.

form property

The ID of the form element with which this element is associated, or null if the element is not associated with any form. This is provided for consistency with the native HTML form property.

Type: string

name property

The name of the form field that will be filled with this element's value. This is an analogue of the standard HTML name property.

Type: string

type property

The "type" of the form field, provided for consistency with the native HTML type property.

If a base class provides a type property, that will be returned. (If this mixin is applied to a class defined by WrappedStandardElement, this will return the type of the inner standard element.) Otherwise, the default value of this property will be the same as the HTML tag name registered for the custom element.

Type: string