Navigation Back to home

CustomControl

A base class for custom controls based on CustomElement.

Import
the javascript logo
import { CustomControl } from "@schukai/monster/source/dom/customcontrol.mjs";
Source
the git logo
Package
the npm logo
Since
1.14.0

Introduction

CustomControl extends CustomElement and adds form association through attachInternals(). It is the base class for Monster form controls like selects, inputs, and composite widgets.

Key Features

  • Form association: Uses ElementInternals to integrate with native forms.
  • Validation hooks: Provides standard form APIs such as setValidity() and reportValidity().
  • Value contract: Derived classes must implement value getter and setter.

Minimal Setup


import { CustomControl } from "@schukai/monster/source/dom/customcontrol.mjs";
import { registerCustomElement } from "@schukai/monster/source/dom/customelement.mjs";

class MyControl extends CustomControl {
  static getTag() {
    return "my-control";
  }

  get value() {
    return "";
  }

  set value(next) {
    // update internal state
  }
}

registerCustomElement(MyControl);

Exported

CustomControl

Derived from

CustomElement

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomElement.

Option
Type
Default
Description
-/-

Properties

The Properties listed in this section are defined directly within the class. This class is derived from several parent classes. Therefore, it inherits Properties from these parent classes. If you cannot find a specific Properties in this list, we recommend consulting the documentation of the CustomElement.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomElement.

Constructor

constructor()
Throws
  • {Error} the ElementInternals is not supported and a polyfill is necessary
The constructor method of CustomControl, which is called when creating a new instance. It checks whether the element supports attachInternals() and initializes an internal form-associated element if supported. Additionally, it initializes a MutationObserver to watch for attribute changes. See the links below for more information: {@link https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-define|CustomElementRegistry.define()} {@link https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-get|CustomElementRegistry.get()} and {@link https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals|ElementInternals}

State query methods

value()
Throws
  • {Error} the value getter must be overwritten by the derived class
Must be overridden by a derived class and return the value of the control. This is a method of [internal API](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals), which is a part of the web standard for custom elements.
value(value)
Parameters
  • value {*}: The value to set.
Throws
  • {Error} the value setter must be overwritten by the derived class
Must be overridden by a derived class and set the value of the control. This is a method of [internal API](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals), which is a part of the web standard for custom elements.
willValidate()
Returns
  • {boolean}
Throws
  • {Error} the ElementInternals is not supported and a polyfill is necessary
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)

Structural methods

setFormValue(value,state)
Parameters
  • value {file|string|formdata}: value
  • state {file|string|formdata}: state
Returns
  • {undefined}
Throws
  • {DOMException} NotSupportedError
  • {Error} the ElementInternals is not supported and a polyfill is necessary
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals) ``// Use the control's name as the base name for submitted data const n = this.getAttribute('name'); const entries = new FormData(); entries.append(n + '-first-name', this.firstName_); entries.append(n + '-last-name', this.lastName_); this.setFormValue(entries);``
setValidity(flags,message,anchor)
Parameters
  • flags {object}: flags
  • message {string|undefined}: message
  • anchor {htmlelement}: anchor
Returns
  • {undefined}
Throws
  • {DOMException} NotSupportedError
  • {Error} the ElementInternals is not supported and a polyfill is necessary

Static methods

[instanceSymbol]()2.1.0
Returns
  • {symbol}
This method is called by the instanceof operator.
observedAttributes()1.15.0
Returns
  • {string[]}
This method determines which attributes are to be monitored by attributeChangedCallback().

Other methods

checkValidity()
Returns
  • {boolean}
Throws
  • {DOMException} NotSupportedError
  • {Error} the ElementInternals is not supported and a polyfill is necessary
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
form()
Returns
  • {HTMLFontElement|null}
Throws
  • {Error} the ElementInternals is not supported and a polyfill is necessary
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
formAssociatedCallback(form)
Parameters
  • form {htmlformelement}: - The form element to associate with the control
Sets the form attribute of the custom control to the id of the passed form element. If no form element is passed, removes the form attribute.
formDisabledCallback(disabled)
Parameters
  • disabled {boolean}: - Whether or not the control should be disabled
Sets or removes the disabled attribute of the custom control based on the passed value.
formResetCallback()
formStateRestoreCallback(state,mode)
Parameters
  • state {string}: state
  • mode {string}: mode
labels()
Returns
  • {NodeList}
Throws
  • {Error} the ElementInternals is not supported and a polyfill is necessary
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
name()
Returns
  • {string|null}
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
reportValidity()
Returns
  • {boolean}
Throws
  • {Error} the ElementInternals is not supported and a polyfill is necessary
  • {DOMException} NotSupportedError
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
states()
Returns
  • {boolean}
Throws
  • {Error} the ElementInternals is not supported and a polyfill is necessary
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
type()
Returns
  • {string}
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
validationMessage()
Returns
  • {string}
Throws
  • {Error} the ElementInternals is not supported and a polyfill is necessary
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
validity()
Returns
  • {ValidityState}
Throws
  • {Error} the ElementInternals is not supported and a polyfill is necessary
This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)

Events

This component does not fire any public events. It may fire events that are inherited from its parent classes.

The current width of the area is too small to display the content correctly.