@material/auto-init
Advanced tools
Declarative, easy-to-use auto-initialization for Material Components for the web
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.
npm install @material/auto-init
material-components-webIf 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.
<div class="mdc-text-field" data-mdc-auto-init="MDCTextField">
<input class="mdc-text-field__input" type="text" id="input">
<label for="input" class="mdc-floating-label">Input Label</label>
<div class="mdc-line-ripple"></div>
</div>
<!-- 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.
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
<div class="mdc-text-field" data-mdc-auto-init="MDCTextField">
<input class="mdc-text-field__input" type="text" id="input">
<label for="input" class="mdc-floating-label">Input Label</label>
<div class="mdc-line-ripple"></div>
</div>
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;
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);
<div class="mdc-text-field" data-mdc-auto-init="My amazing text field!!!">
<!-- ... -->
</div>
<script>window.mdc.autoInit();</script>
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().
mdc-auto-init worksmdc-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:
data-mdc-auto-init attribute does not have a value associated with it, throw an errordata-mdc-auto-init cannot be found in the registry, throw an errordata-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).Ctor be the component constructor associated with the given name in the registerinstance be the result of calling Ctor.attachTo() and passing in the element as an
argument.data-mdc-auto-init and whose value is instance.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.
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.
Triggered when initialization of all components is complete.
document.addEventListener("MDCAutoInit:End", () => {...});
12.0.0 (2021-07-27)
return statement into MDCTooltipComponent#isShown method. (4d95812)mdc-card__ripple element rather than the mdc-card__primary-action. (8ace3b8)#close within #destroy. (5631828)forceUpdate option to #setSelectedIndex that forces a UI update of the selected item. (5d06051)transform-origin for tooltips with caret so that the entrance animation originates from the caret. (1a8d064)tranform-origin. (25751d2)data-hide-tooltip-from-screenreader="true" (in addition to using data-tooltip-id rather than aria-describedby.PiperOrigin-RevId: 386490861
window.mdc.circularProgress to window.mdc['circular-progress].PiperOrigin-RevId: 384568221
mdc-icon-button__ripple. See README for details.PiperOrigin-RevId: 372153409
FAQs
Declarative, easy-to-use auto-initialization for Material Components for the web
The npm package @material/auto-init receives a total of 604,846 weekly downloads. As such, @material/auto-init popularity was classified as popular.
We found that @material/auto-init demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 15 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."