Security News
The Hidden Blast Radius of the Axios Compromise
The Axios compromise shows how time-dependent dependency resolution makes exposure harder to detect and contain.
By Ahmad Nassri - Apr 01, 2026
New Research: Supply Chain Attack on Axios Pulls Malicious Dependency from npm.Details → →
blue-widgets
Advanced tools
blue-widgets
A class-based widget library for adding complex javascript functionality to existing DOM elements
blue-widgets
blue-widgets** is a class-based widget library for adding complex javascript functionality to existing DOM elements
v3 breaking changes
WeakMap() support required
Parse order has changed of the widgets in order to better support composeability. So whereas before widgets were parsed in the order they were discovered, now descendant widgets are parsed first. So if I now call getDescendants in the onWidgetsReady lifecycle method, all descendants will have already been initialised.
Browser Support
IE11+ and all other modern browsers out of the box. For support down to IE9 you'll need to polyfill WeakMap()
Installation
npm install blue-widgets
Tutorial
Creating a basic widget
Take this html:
<body>
<div data-widget="ShowHide">
<a href="#" data-trigger>ShowHide trigger - click me!</a>
<div data-content>
<p>Some example content</p>
<p>Some more example content</p>
<table>
<tr>
<td>
test
</td>
</tr>
</table>
</div>
</div>
</body>
Create our widget Class
In ./widgets/ShowHide/index.js
import { hasClass, toggleClass } from 'blue-js'
import { Widget } from 'blue-widgets'
const OPEN_CLASS = 'is-open'
class ShowHide extends Widget {
constructor (el) {
super(el)
this.trigger = el.querySelector('[data-trigger]')
this.content = el.querySelector('[data-content]')
this.content.style.display = hasClass(el, OPEN_CLASS) ? 'block' : 'none'
this.trigger.addEventListener('click', this.onTriggerClick.bind(this), false)
}
onTriggerClick (event) {
event.preventDefault()
this.toggle()
}
toggle () {
this.content.style.display = hasClass(this.el, OPEN_CLASS) ? 'none' : 'block'
toggleClass(this.el, OPEN_CLASS)
}
}
export default ShowHide
Add widget to registry and parse for widgets in app.js
import { defineWidgets, parse } from 'blue-widgets'
import ShowHide from './widgets/ShowHide'
// Add widgets to the registry
defineWidgets({
ShowHide
})
/* NOTE: this is the ES6 equivalent of
defineWidgets({
ShowHide: ShowHide
})
*/
// Parse the dom for widget instances
parse()
API
Classes
Functions
- defineWidgets(widgets)
Adds an object of widget classes to the registry library
- parse(el, [pattern], [typeFn]) ⇒
Promise.<Array> Parse an element for widget instances and add them to the registry. By default looks for elements with a
data-widgetattribute- getInstance(ref)
Get a widget instance from the registry
- getDescendants(parent, [widgetType]) ⇒
array Gets all descendants of the passed element.
- destroyInstance(widgetRef, [recursive])
Removes a widget instance from the registry (doesn't remove the element itself, just the widget instances)
- destroyDescendants(parent, [widgetType])
Removes descendant widgets from the registry (does not remove the actual dom nodes)
Widget
Kind: global class
- Widget
- new Widget(el, [opts])
- .el :
HTMLElement - .ref :
String - .options :
Object - .getOptions() ⇒
Object - .onWidgetsReady()
- .beforeRemove()
new Widget(el, [opts])
The base Widget class from which other widgets are extended. Technically the parser can create widgets using any Class at all (rather than only ones that extend off the Widget class). This base widget provides some convenience setup options and lifecycle methods that work well with the parser/registry though.
| Param | Type | Description |
|---|---|---|
| el | HTMLElement | The dom node of the Widget instance |
| [opts] | Object | Optional options to be passed to the constructor. Only used if the widget is constructed directly (using the new keyword rather than using the parser) |
widget.el : HTMLElement
The html element that the instance was created using
Kind: instance property of Widget
widget.ref : String
The reference of the widget in the registry. Only set if the widget was created using the parser. Defaults to the elements data-ref attribute - if not set the registry will automatically create a unique ref during parsing.
Kind: instance property of Widget
Default: 'The elements data-ref attribute'
Read only: true
widget.options : Object
The widget options. An object created by merging this.getOptions(), opts from the constructor, and the base elements dataset.
Kind: instance property of Widget
Example
class CustomWidget extends Widget {
// The default widget options
getOptions () {
return { openClass: 'is-open' }
}
}
// Override option in the html <div data-widget="CustomWidget" data-open-class="open">
// this.options in the widget instance would be { openClass: 'open' } in this case
widget.getOptions() ⇒ Object
Returns the default widget options
Kind: instance method of Widget
Returns: Object - The default widget options
widget.onWidgetsReady()
Lifecycle method: Fires when all widgets in the current parse cycle have been created
Kind: instance method of Widget
widget.beforeRemove()
Lifecycle method: Fires when a widget is destroyed using registry.destroy or registry.destroyDescendants
Kind: instance method of Widget
defineWidgets(widgets)
Adds an object of widget classes to the registry library
Kind: global function
| Param | Type | Description |
|---|---|---|
| widgets | Object.<string, Class> | Object of key value pair widgets to add to the library. The key is the name and the value is the Class itself |
parse(el, [pattern], [typeFn]) ⇒ Promise.<Array>
Parse an element for widget instances and add them to the registry. By default looks for elements with a data-widget attribute
Kind: global function
Returns: Promise.<Array> - A Promise fulfilled with an array of the parsed instances
| Param | Type | Default | Description |
|---|---|---|---|
| el | HTMLElement | A dom element | |
| [pattern] | string | "[data-widget]" | Optional string for setting the selector pattern to match in the querySelectorAll call |
| [typeFn] | function | el => el.dataset.widget | Optional function for returning the type to look up in the registry' |
getInstance(ref)
Get a widget instance from the registry
Kind: global function
| Param | Type | Description |
|---|---|---|
| ref | string | HTMLElement | The ref of the widget we want to fetch, or the actual html element the widget was created on |
getDescendants(parent, [widgetType]) ⇒ array
Gets all descendants of the passed element.
Kind: global function
Returns: array - An array containing the matching descendants
| Param | Type | Description |
|---|---|---|
| parent | HTMLElement | The parent dom element |
| [widgetType] | string | Class | The type of the widget - as a string will only match instances of those widget classes that are stored under that exact name - as a Class will match all widgets that are instances of that class including subclasses. |
destroyInstance(widgetRef, [recursive])
Removes a widget instance from the registry (doesn't remove the element itself, just the widget instances)
Kind: global function
| Param | Type | Default | Description |
|---|---|---|---|
| widgetRef | string | HTMLElement | The ref of the widget we want to remove, or the actual html element the widget was created on | |
| [recursive] | boolean | true | Whether to also destory a widgets descendants |
destroyDescendants(parent, [widgetType])
Removes descendant widgets from the registry (does not remove the actual dom nodes)
Kind: global function
| Param | Type | Description |
|---|---|---|
| parent | HTMLElement | The parent dom element |
| [widgetType] | string | Class | Optional type of the widget children to remove - as a string will only match instances of those widget classes that are stored under that exact name - as a Class will match all widgets that are instances of that class including subclasses. |
FAQs
A class-based widget library for adding complex javascript functionality to existing DOM elements
We found that blue-widgets demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Package last updated on 26 Feb 2019
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.
Related posts
Research
Supply Chain Attack on Axios Pulls Malicious Dependency from npm
A supply chain attack on Axios introduced a malicious dependency, plain-crypto-js@4.2.1, published minutes earlier and absent from the project’s GitHub releases.
By Socket Research Team - Mar 31, 2026
Research
TeamPCP Compromises Telnyx Python SDK to Deliver Credential-Stealing Malware
Malicious versions of the Telnyx Python SDK on PyPI delivered credential-stealing malware via a multi-stage supply chain attack.
By Socket Research Team - Mar 27, 2026