Lightweight DOM Utility

2.0.0 · abandoned · verified Tue Apr 21

Bonzo is a library-agnostic, extensible DOM manipulation utility designed to be minimalist and work with or without a host library like Ender.js. It provides a chainable API for common DOM tasks such as adding/removing classes, manipulating CSS, appending/prepending elements, and iterating over collections. Version 2.0.0, published in 2012, is the latest release and the package has been largely unmaintained since then. It differentiates itself from larger libraries like jQuery by focusing solely on DOM manipulation and explicitly requiring integration with external selector engines (e.g., Qwery) for CSS-style selections, rather than including one internally. Its release cadence was irregular, and it is now considered abandoned.

Common errors

```
ReferenceError: bonzo is not defined
```
cause The Bonzo library script has not been loaded or correctly imported into the current scope.

fix Ensure `bonzo.js` is included in your HTML `<head>` or `<body>` tag before your scripts, or use `const bonzo = require('bonzo');` in a CommonJS environment.
```
Uncaught TypeError: $(...).hide is not a function
```
cause This usually indicates that `$` is not a Bonzo instance, or Bonzo has not been correctly wrapped around a selector engine.

fix Verify that your `$` function returns `bonzo(selectorEngine(selector))` and that `bonzo` itself is correctly loaded and accessible. Ensure you are passing actual DOM elements to `bonzo()` if not using a selector wrapper.

Warnings

breaking Bonzo relies on older JavaScript patterns (CommonJS/global) and lacks native ES Module support. Direct 'import' statements will fail without a legacy transpilation setup.
Fix: Use CommonJS 'require()' for Node.js environments or ensure the script is loaded globally in browsers. Consider using a modern DOM library if ES Modules are required.
gotcha Bonzo does not include a built-in selector engine. To select elements using CSS selectors (e.g., `$('.my-class')`), you must integrate it with an external library like Qwery or Sizzle.
Fix: Implement a wrapper function, e.g., `function $(selector) { return bonzo(qwery(selector)); }`, or obtain DOM elements via `document.getElementById`, `document.querySelectorAll`, etc., before passing them to bonzo().
deprecated The Bonzo library is no longer actively maintained. The last release was in 2012, meaning it may have compatibility issues with modern browsers or security vulnerabilities that will not be patched.
Fix: For new projects, consider modern, actively maintained DOM manipulation libraries or use native DOM APIs. For existing projects, be aware of potential risks and thoroughly test cross-browser compatibility.
gotcha Bonzo's API expects an array of DOM elements or a single DOM element. Passing HTML strings directly to the constructor will not work as expected for element selection.
Fix: If you have an HTML string, you can either create elements first (e.g., `document.createElement('div')`) or use methods like `.append()` which accept HTML strings to add content to existing elements.

Install

npm install bonzo npm
yarn add bonzo yarn
pnpm add bonzo pnpm

Imports

bonzo
wrong:
```
import bonzo from 'bonzo';
```
correct:
```
const bonzo = require('bonzo');
```
Primarily designed for CommonJS or global script inclusion. Does not support ES Modules natively.
bonzo(elements)
```
const $elements = bonzo([document.getElementById('my-id')]);
```
The primary way to use Bonzo is by passing an array of DOM elements or a single DOM element to its constructor function, which returns a Bonzo instance for chaining.
bonzo.aug
wrong:
```
Bonzo.aug({...});
```
correct:
```
bonzo.aug({ myMethod: function() { /* ... */ } });
```
Used to extend Bonzo instances with custom methods. 'aug' is a static method on the `bonzo` function itself.

Quickstart

Demonstrates basic DOM manipulation using Bonzo's chainable API, including class manipulation, CSS styling, element insertion, and extending Bonzo with a custom method. It shows how to work with elements directly as Bonzo does not include a selector engine.

// This example demonstrates basic DOM manipulation using Bonzo,
// typically combined with a selector engine like Qwery.
// As Bonzo is a global or CommonJS export, we simulate its availability.

// In a browser, Bonzo might be available globally:
// <script src="path/to/bonzo.js"></script>

// For demonstration, let's assume 'bonzo' is available.
// In a real scenario, if using CommonJS:
// const bonzo = require('bonzo');

const elements = [
  document.createElement('div'),
  document.createElement('p')
];

elements[0].id = 'bonzo-container';
elements[1].textContent = 'Hello from Bonzo!';
document.body.appendChild(elements[0]);
elements[0].appendChild(elements[1]);

bonzo(elements[0])
  .hide() // Initially hide the element
  .addClass('bonzo-managed-element')
  .append('<span>Appended content with Bonzo!</span>')
  .css({
    color: 'darkgreen',
    'font-size': '16px',
    'border': '1px dashed #ccc'
  })
  .show() // Then show it with new styles and content
  .after('<div class="sibling-element">I am a sibling added after.</div>');

// You can also extend Bonzo with custom methods:
bonzo.aug({
  highlight: function (color) {
    return this.css('background-color', color || 'yellow');
  }
});

// Now use the custom method
bonzo(elements[1]).highlight('lightblue');

console.log('Bonzo operations complete, check the DOM!');

view raw JSON →