2.2.3 • Public • Published


Robust Web Component interface, based on @wide/dom-observer.


npm install @wide/modulus --save


Register a regular component

import modulus from '@wide/modulus'

modulus.component('foo-bar', class {
  run() {


// or batch
  'foo-bar': class {
    run() {

  <div is="foo-bar">Hey!</div>

Register a web component

The name given to the component must contains a - to comply to the custom-element naming convention.

import modulus from '@wide/modulus'

modulus.webComponent('foo-bar', class {
  run() {


// or batch
  'foo-bar': class {
    run() {


Get all components by name and selector

import modulus from '@wide/modulus'

modulus.seekAll('foo-bar') // Array<FooBar>
modulus.seekAll('foo-bar', '.visible') // Array<FooBar.visible>

Get one component by name and selector

import modulus from '@wide/modulus'

modulus.seek('foo-bar') // first FooBar instance
modulus.seek('foo-bar', '#foobar1') // FooBar#foobar1 instance

Get component(s) from external source

document.queryComponent('foo-bar') // first FooBar instance
document.queryComponents('foo-bar', '.visible') // Array<FooBar.visible>

Call component's method from html

Use the [data-call] helper with a formatted value name#id.method:

<button data-call="modal#register.open">do something</button>

will internally trigger:

modulus.seek('modal', '#register').open({ el, e, data })
Value Description
el HTMLElement object binded to the event
e Event object of the event listener method callback
data Optional parameters defined in [data-call.params]


Use the [data-call.params] to pass custom values:

<button data-call="modal#register.open" data-call.params='[{ "myAttr": "myValue" }]'>do something</button>

⚠️ Note: data-call.params is waiting a JSON format only

Exmple with the previous HTML code:

modulus.component('modal', class extends Component {
  run() {
    // ...

   * Open modal and do some stuff
   * @params {HTMLElement} el
   * @params {Event} e
   * @params {Object|null} [data]
  open({ el, e, data }) {
    // el: <button ...>
    // e: Event{ ... }
    // data: { ... } | null

Deprecated method: To ensure compatibility with the old $event and $el parameters (used by Modulus below v2.2.0), it still possible to use them. For this, consult the old documentation.

⚠️ Note: Keep in mind that this method should not be used with new projects. It can be removed at any time on the next release.

Component class

The Component class offers shortcuts for accessing element or sending events to other components.

import modulus from '@wide/modulus'
import Component from '@wide/modulus/src/component'

modulus.component('foo-bar', class extends Component {
  run() {
    this.log(`I'm in the DOM !`)
  destroy() {
    this.log(`I'm no longer in the DOM...`)


  • el the DOM element binded to the class
  • uid unique ID given at the registration
  • attrs element's attributes
  • dataset element's data-attributes
  • refs element's specific children (fetched using [ref] and [ref.dyn] attributes)
    • [ref] elements are computed on component initial load
    • [ref.dyn] elements are computed on each access
    • [ref.group] elements are grouped in an array under the same key ([ref=bar] -> this.refs.bar[0])


  • run() hook called when the element is inserted in DOM
  • destroy() hook called when the element is removed from DOM


  • child(selector) alias of this.el.querySelector(), return HTMLElement
  • children(selector) alias of this.el.querySelectorAll(), return NodeList
  • on(event, callback) listen global event
  • emit(event, callback) trigger global event
  • off(event, callback) remove global listener
  • log(...args) log message with unique identifier
  • log.info(...args) log message with INFO severity
  • log.warn(...args) log message with WARN severity
  • log.error(...args) log message with ERROR severity

Garbage Collector

Every event listeners created using this.on() are automatically off()ed on component destruction.


Log level

To keep only warn and error logs (for production usage), set production to true:

import modulus from '@wide/modulus'

modulus.config({ production: true })

Or manually assign a log level:

import modulus, { LOG_LEVELS } from '@wide/modulus'

  log: {
    level: LOG_LEVELS.INFO // DEBUG (default), INFO, WARN, ERROR, NONE

⚠️ Note: assign a log level will override the production setting.

To disable logs, set enabled to false:

import modulus from '@wide/modulus'

  log: {
    enabled: false

The default config is setted to show all kind of logs.




This project is licensed under the MIT License - see the licence file for details




Package Sidebar


npm i @wide/modulus

Weekly Downloads






Unpacked Size

52.7 kB

Total Files


Last publish


  • gflandin
  • myeti
  • jmartinsdacosta
  • robiseb