@material/auto-init

Auto Init

mdc-auto-init is a utility package that provides declarative, DOM-based method of initialization for MDC Web components on simple web sites. Note that for more advanced use-cases and complex sites, manual instantiation of components will give you more flexibility. However, mdc-auto-init is great for static websites, prototypes, and other use-cases where simplicity and convenience is most appropriate.

Installation

npm install @material/auto-init

Usage

Using as part of material-components-web

If you are using mdc-auto-init as part of the material-components-web package, simply write the necessary DOM needed for a component, and attach a data-mdc-auto-init attribute to the root element with its value set to the component's JavaScript class name (e.g., MDCTextField). Then, after writing the markup, simply insert a script tag that calls mdc.autoInit(). Make sure you call mdc.autoInit() after all scripts are loaded so it works properly.

<label class="mdc-text-field mdc-text-field--filled" data-mdc-auto-init="MDCTextField">
  <span class="mdc-text-field__ripple"></span>
  <input class="mdc-text-field__input" type="text" aria-labelledby="label">
  <span id="label" class="mdc-floating-label">Input Label</span>
  <span class="mdc-line-ripple"></span>
</label>

<!-- at the bottom of the page -->
<script type="text/javascript">
  window.mdc.autoInit();
</script>

This will attach an MDCTextField instance to the root <div> element.

Accessing the component instance

When mdc-auto-init attaches a component to an element, it assign that instance to the element using a property whose name is the value of data-mdc-auto-init. For example, given

<label class="mdc-text-field mdc-text-field--filled" data-mdc-auto-init="MDCTextField">
  <span class="mdc-text-field__ripple"></span>
  <input class="mdc-text-field__input" type="text" aria-labelledby="label">
  <span id="label" class="mdc-floating-label">Input Label</span>
  <span class="mdc-line-ripple"></span>
</label>

Once mdc.autoInit() is called, you can access the component instance via an MDCTextField property on that element.

document.querySelector('.mdc-text-field').MDCTextField.disabled = true;

Calling subsequent mdc.autoInit()

If you decide to add new components into the DOM after the initial mdc.autoInit(), you can make subsequent calls to mdc.autoInit(). This will not reinitialize existing components. This works since mdc-auto-init will add the data-mdc-auto-init-state="initialized" attribute, which tracks if the component has already been initialized. After calling mdc.autoInit() your component will then look like:

<label class="mdc-text-field mdc-text-field--filled" data-mdc-auto-init="MDCTextField" data-mdc-auto-init-state="initialized">
  ...
</label>

Using as a standalone module

Registering Components

If you are using mdc-auto-init outside of material-components-web, you must manually provide a mapping between data-mdc-auto-init attribute values and the components which they map to. This can be achieved via mdcAutoInit.register.

import mdcAutoInit from '@material/auto-init';
import {MDCTextField} from '@material/textfield';

mdcAutoInit.register('MDCTextField', MDCTextField);

mdcAutoInit.register() tells mdc-auto-init that when it comes across an element with a data-mdc-auto-init attribute set to "MDCTextField", it should initialize an MDCTextField instance on that element. The material-components-web package does this for all components for convenience.

Also note that a component can be mapped to any string, not necessarily the name of its constructor.

import mdcAutoInit from '@material/auto-init';
import {MDCTextField} from '@material/textfield';

mdcAutoInit.register('My amazing text field!!!', MDCTextField);

<label class="mdc-text-field mdc-text-field--filled" data-mdc-auto-init="My amazing text field!!!">
  <!-- ... -->
</label>
<script>window.mdc.autoInit();</script>

De-registering components

Any component can be deregistered by calling mdcAutoInit.deregister with the name used to register the component.

mdcAutoInit.deregister('MDCTextField');

This will simply remove the name -> component mapping. It will not affect any already-instantiated components on the page.

To unregister all name -> component mappings, you can use mdcAutoInit.deregisterAll().

How mdc-auto-init works

mdc-auto-init maintains a registry object which maps string identifiers, or names, to component constructors. When the default exported function - mdcAutoInit() - is called, mdc-auto-init queries the DOM for all elements with a data-mdc-auto-init attribute. For each element returned, the following steps are taken:

• If the data-mdc-auto-init attribute does not have a value associated with it, throw an error
• If the value of data-mdc-auto-init cannot be found in the registry, throw an error
• If the element has an existing property whose name is the value of data-mdc-auto-init, it is assumed to have already been initialized. Therefore it is skipped, and a warning will be logged to the console (this behavior can be overridden).
• Let Ctor be the component constructor associated with the given name in the register
• Let instance be the result of calling Ctor.attachTo() and passing in the element as an argument.
• Create a non-writable, non-enumerable property on the node whose name is the value of data-mdc-auto-init and whose value is instance.

Initializing only a certain part of the page

By default, mdc-auto-init will query the entire document to figure out which components to initialize. To override this behavior, you can pass in an optional root first argument specifying the root node whose children will be queried for instantiation.

<div id="mdc-section">
  <!-- MDC Web Components, etc. -->
</div>
<script>window.mdc.autoInit(document.getElementById('mdc-section'));</script>

In the above example, only elements within <div id="mdc-section"> will be queried.

Calling autoInit() multiple times

By default, mdc-auto-init only expects to be called once, at page-load time. However, there may be certain scenarios where one may want to use mdc-auto-init and may still need to call it multiple times, such as on a Wordpress site that contains an infinitely-scrolling list of new blog post elements containing MDC Web components. mdcAutoInit() takes an optional second argument which is the function used to warn users when a component is initialized multiple times. By default, this is just console.warn(). However, to skip over already-initialized components without logging a warning, you could simply pass in a nop.

<script>window.mdc.autoInit(/* root */ document, () => {});</script>

This will suppress any warnings about already initialized elements.

Events

MDCAutoInit:End

Triggered when initialization of all components is complete.

document.addEventListener("MDCAutoInit:End", () => {...});

Changelog

14.0.0 (2022-04-27)

Bug Fixes

• button: update HCM shim to use the existing focus-ring (a657abb)
• checkbox: Add explicit system color for checkmark in HCM. (8c4da22)
• checkbox: move forced-colors theme out of static styles (bbd1126)
• checkbox: Update checkbox theme styles mixin to accept css vars (c14e977)
• chips: Fix typography selector in GMDC-Wiz chips theming (43c7d87)
• datatable: Adjust data table last row border-radius to support setting row background-color. (ba78e87)
• dialog: Render dividers in Firefox 94 on Windows HCM (fae6c65)
• dialog: Set default z-index for close button in FloatingSheet dialog. (3366a71)
• fab: Add focus ring in HCM. (d57ec74)
• focus-ring: add 2d padding customizability, RTL bugfix (f81fb1d)
• focus-ring: box-sizing bugfix to content-box. If box-sizing border-box is inherited the ring spacing will collapse. (e58552c)
• focus-ring: ignore pointer events (3ef470e)
• focus-ring: RTL bugfix (e00181e)
• iconbutton: Fixed max width and height for high contrast mode focus ring on icon buttons. Display only in forced colors mode. (cf42927)
• iconbutton: Set icon button ripple z-index to -1. (586e740)
• list: Improve a11y for multi-select lists (9736ddc)
• list: Remove conflicting validation for checkbox list in setEnabled (353ca7e)
• list: Update lastSelectedIndex when toggling a checkbox range (dcba26f)
• menusurface: Add a getOwnerDocument() method to MDCMenuSurfaceAdapter to provide a reference to the document that owns the menu surface DOM element. (3486659)
• radio: Fix disabled state in Firefox Windows high contrast mode (23043ac)
• radio: Modify theme styles Sass mixin validation to validate only keys (390220e)
• select: Add border to select menu in HCM. (5d80969)
• select: revert down/up arrow on anchor changing selected index (43d08ba)
• slider: Fix bug where secondary click moves slider thumb. (3ab9565)
• slider: Fix IE11 bug - unset is unsupported in IE. (f460e23)
• slider: In updateUI, fix behavior to match jsdoc claim that when thumb param is undefined it updates both thumbs. Input attributes were not being updated at all. (cc4ed13)
• slider: Make the slider errors easier to debug by providing all relevant values in the error message. (8687937)
• snackbar: address Trusted Types violation (cbd9358)
• tooltip: Adjusts logic in validateTooltipWithCaretDistances method. (3e30054)
• typography: Fixes typography theme-styles mixin... the value being retreived from the $theme map and css property name was swapped. The mixin would request font-size/font-weight/letter-spacing from the $theme map (which expects size/weight/tracking)... so these values would always be null. (32b3913)
• Remove /** @override */ tags from TypeScript code. (c3cdff0)
• Simplify MDCAttachable interface to be any object (Function) that has attachTo. (05db65e)
• Snackbar action button ripple color is applied to the ripple element. (4e66fb2)
• Work around bug in Sass (037285f), closes sass/sass#3259
• switch: Restore Firefox 94 HCM outlines (39cf14b)
• textfield: Fix breaking tests due to no valid pointerId being associated with pointer events. (15db4f1)
• tooltip: Only sends notification of a tooltip being hidden if showTimeout is not set (indicating that this tooltip is about to be re-shown). (6ca8b8f)

Features

• banner: Add disableAutoClose params for both banner actions to prevent the banner buttons from automatically closing the banner. Add adapter #notifyActionClicked method. (b094eaa)
• chips: add focus ring styles (783f6fd)
• chips: Added elevation tint layer color support in chips (c78ff04)
• data-table: separate table structure into its own mixin (9f9d928)
• dialog: Add styling for floating sheets (78305b6)
• dialog: Add styling for floating sheets with content padding (3e20c1d)
• Dialog: Adds an API to hide the header for GMDC Fullscreen Dialog in non-fullscreen mode (ab4aba1)
• Dialog: Adds an API to set custom position for GMDC Dialog (ea9b5b4)
• Dialog: Adds an API to set custom z-index for GMDC Dialog (96ea061)
• focus-ring: added a new mixin so we can override just the focus-ring color (641ed08)
• focus-ring: added a new mixin so we can override just the focus-ring radius (7321d62)
• iconbutton: Add link icon button Sass. (9803d2d)
• mdc-list: introduce selection change event (7d8ea46)
• menu: allow preferentially opening surface below anchor (261f2db)
• MenuSurface: Add opening event for menus. (53b3cad)
• select: Add theming mixin boilerplate code to select (ae8a6a3)
• select: Add validation getter methods. (bdf1d37)
• select: Added theme mixins to MDC select (dcfe49c)
• slider: Add minRange param to range sliders to request a minimum gap between the two thumbs. (8fffcb5)
• slider: Add an option to hide focus styles after pointer interaction. (ec54d90)
• slider: Keep the slider value indicator within the bounds of the slider if possible. (c047f7c)
• state: make context aware (b2fe352)
• switch: Add high contrast mode focus ring to switch (f31a833)
• text-field: Add theming mixin boilerplate code to text-field (eb382f3)
• text-field: Added theme mixins to MDC text field (344d528)
• textfield: adding input-font-size mixin (207230e)
• theme: allow custom property strings in theme.validate-theme() (4e372fb)
• add new class and mixin for open state of a menu item (9a02b6e)
• Indicate which thumb valueToAriaValueTextFn and valueToValueIndicatorTextFn functions are called for. (b6510c8)
• textfield: adding input-font-family mixin (991fb99)
• Describe how to add child lists into a list item. (758ce31)

BREAKING CHANGES

• MenuSurface: Adds #notifyOpening method to menu surface adapter.

PiperOrigin-RevId: 444830518

• slider: Adds #getValueIndicatorContainerWidth method to slider adapter.

PiperOrigin-RevId: 419837612

Similar packages

Other packages similar to @material/auto-init

webcomponentsjs

webcomponentsjs is a polyfill library for Web Components, which includes a custom elements feature that can be used to define and initialize custom elements. While it doesn't provide auto-initialization out of the box like @material/auto-init, it allows for the creation of custom elements that can be initialized when added to the DOM.