argyleink/blingblingjs

💲 Micro-library of shorthands for DOM selection, events, and attribute manipulation

BlingBlingJS

like bling.js, but more bling

Getting Started

Installation

npm i blingblingjs

Importing

// import the blingbling y'all
import $ from 'blingblingjs'                // es6 module
const $ = require('blingblingjs')           // commonjs

// or from Pika CDN! https://cdn.pika.dev/blingblingjs/v2

Bookmarklet

javascript: fetch('https://cdn.jsdelivr.net/npm/blingblingjs@latest/dist/index.min.js').then((x) => x.text()).then((x) => {
  eval(x); $ = $.default;
  console.log("💲 BlingBlingJS ready 💲");
});

Syntax

Quick Overview

$()        // select nodes in document or pass nodes in
$().on     // add multiple event listeners to multiple nodes
$().off    // remove multiple event listeners from multiple nodes
$().attr   // CRUD attributes on nodes
$().map    // use native array methods

Queries

// get nodes from the document
const btns         = $('button')            // blingbling always returns an array
const [first_btn]  = $('button[primary]')   // destructure shortcut for 1st/only match
const btn_spans    = $('span', btns)        // provide a query context by passing a 2nd param of node/nodes

// cover DOM nodes in bling
const [sugared_single]  = $(document.querySelector('button'))
const sugared_buttons   = $(document.querySelectorAll('button'))

Array Methods

$('button').forEach(...)
$('button').map(...)

const btns = $('button')
btns.filter(...)
btns.reduce(...)
btns.flatMap(...)
...

Events

// single events
first_btn.on('click', ({target}) => console.log(target))
$('button[primary]').on('click', e => console.log(e))

// single events with options
first_btn.on('click', ({target}) => console.log(target), {once: true})
$('button[primary]').on('click', e => console.log(e), true) // useCapture

// multiple events
$('h1').on('click touchend', ({target}) => console.log(target))

// remove events
const log_event = e => console.warn(e) // must have a reference to the original function
main_btn.on('contextmenu', log_event)
main_btn.off('contextmenu', log_event)

Attributes

// set an attribute
$('button.rad').attr('rad', true)

// set multiple attributes
const [rad_btn] = $('button.rad')
rad_btn.attr({
  test: 'foo',
  hi:   'bye',
})

// get an attribute
rad_btn.attr('rad')        // "true"
rad_btn.attr('hi')         // "bye"

// get multiple attributes
$('button').map(btn => ({
  tests:  btn.attr('tests'),
  hi:     btn.attr('hi'),
}))

// remove an attribute
rad_btn.attr('hi', null)   // set to null to remove
rad_btn.attr('hi')         // attribute not found

// remove multiple attributes
btns.attr({
  test:   null,
  hi:     null,
})

Convenience

import {rIC, rAF} from 'blingblingjs'

// requestAnimationFrame
rAF(_ => {
  // animation tick
})

// requestIdleCallback
rIC(_ => {
  // good time to compute
})

What for?

Developer ergonomics! If you agree with any of the following, you may appreciate this micro library:

• Love vanilla js, want to keep your code close to it
• Chaining is fun, Arrays are fun, essentially a functional programming fan
• Hate typing document.querySelector over.. and over..
• Hate typing addEventListener over.. and over..
• Really wish document.querySelectorAll had array methods on it..
• Confused that there is no node.setAttributes({...}) or even better nodeList.setAttributes({...})
• Liked jQuery selector syntax

Why BlingBling?

• Minimal at 0.6kb (636 bytes)
• BlingBling supports ES6 module importing and common module loading
• Supports chaining
• Worth it's weight (should save more characters than it loads)
• Only enhances the nodes you query with it
• ES6 version of popular bling.js by Paul Irish
• Tested