JavaScript - Hummingbird

This guide provides an overview of Hummingbird's JavaScript components, including how to initialize and use them in projects.

Hummingbird creates interactive components using Bootstrap’s JavaScript plugins. Hummingbird ensures smooth interactivity, accessibility, and consistent behavior across browsers. With built-in TypeScript support, every plugin is type-safe and developer-friendly, making it easier to extend, customize, and integrate into modern workflows.

Include plugins

Plugins can be included individually or all at once.

Include all plugins:

<script src="../path/to/@hummingbirdui/hummingbird/dist/hummingbird.bundle.min.js"></script>

Alternatively, if using a build system (like Vite or Webpack), import Hummingbird directly in the JavaScript entry file.

import "@hummingbirdui/hummingbird";

Another quickest way to include Hummingbird script in a project is via CDN link.

<script src="https://cdn.jsdelivr.net/npm/@hummingbirdui/hummingbird@0.0.0-insiders.3.0/dist/hummingbird.bundle.min.js"></script>

Include individual plugins:

<script src="../path/to/@hummingbirdui/hummingbird/lib/esm/scripts/modal.js"></script>

Alternatively, individual plugins can be imported into a JavaScript file.

import "@hummingbirdui/hummingbird/lib/esm/scripts/modal";

Optimization

To reduce the final bundle size, import only the specific JavaScript plugins needed.

The example below shows how to import only the Modal plugin:

// import "@hummingbirdui/hummingbird/lib/esm/scripts/alert";
// import "@hummingbirdui/hummingbird/lib/esm/scripts/button";
// import "@hummingbirdui/hummingbird/lib/esm/scripts/carousel";
// import "@hummingbirdui/hummingbird/lib/esm/scripts/collapse";
// import "@hummingbirdui/hummingbird/lib/esm/scripts/dropdown";
import "@hummingbirdui/hummingbird/lib/esm/scripts/modal";
// import "@hummingbirdui/hummingbird/lib/esm/scripts/offcanvas";
// import "@hummingbirdui/hummingbird/lib/esm/scripts/popover";
// import "@hummingbirdui/hummingbird/lib/esm/scripts/scrollspy";
// import "@hummingbirdui/hummingbird/lib/esm/scripts/tab";
// import "@hummingbirdui/hummingbird/lib/esm/scripts/toast";
// import "@hummingbirdui/hummingbird/lib/esm/scripts/tooltip";

The example below demonstrates how to efficiently control the Modal component programmatically by importing only the Modal plugin.

import Modal from "@hummingbirdui/hummingbird/lib/esm/scripts/modal";
const openBtn = document.querySelector("[data-open-demo-modal]");
const myModal = new Modal(".modal");

openBtn.addEventListener("click", () => {
  myModal.show();
});

JavaScript API

Hummingbird also provides a JavaScript API for programmatic control of components. For example, any modal can be manually toggled using the API.

Here’s how to initialize and use the Modal component:

<button class="btn btn-primary" data-open-demo-modal>Open Modal</button>
<div class="modal" id="demo-modal" tabindex="-1" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title">Demo Modal</h5>
        <button type="button" class="btn-close" data-dismiss="modal" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        <p>This is a demo modal.</p>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary me-2" data-bs-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

const openBtn = document.querySelector("[data-open-demo-modal]");
const myModal = new window.hummingbird.Modal(".modal");

openBtn.addEventListener("click", () => {
myModal.show();
});

When using a build system such as Vite or Webpack, import Modal as shown below.

import { Modal } from "@hummingbirdui/hummingbird";
const openBtn = document.querySelector("[data-open-demo-modal]");
const myModal = new Modal(".modal");

openBtn.addEventListener("click", () => {
myModal.show();
});

TypeScript support

Hummingbird includes TypeScript definitions for all components. Import Hummingbird plugins with their types while using TypeScript.

import { Modal } from "@hummingbirdui/hummingbird";
import { type ModalClass, type ModalInstance, type ModalOptions } from "@hummingbirdui/hummingbird";

ESM vs CJS

Hummingbird supports both ESM and CJS builds, so it works with different environments:

  • ESM: Used by modern bundlers like Vite, Rollup, and Webpack 5+. If the project is using ES modules (import syntax), this is what gets loaded automatically.

  • CJS: Used in Node.js or older tooling that relies on require(). If the environment doesn’t support ESM, bundlers and Node will fall back to this file.

No manual choice is required; the bundler or runtime will select the correct version based on the setup.

Integration with frameworks

Hummingbird can be integrated into various JavaScript frameworks, including React, Vue, Angular, and more. Leverage its components within these frameworks by following best practices for DOM manipulation and component lifecycle management.

Follow the framework-specific guidelines to ensure smooth integration and optimal performance.

Dependencies

Some JavaScript components rely on Popper for positioning elements, such as dropdowns, tooltips, and popovers. When using these components, include Popper.js in the project, or use hummingbird.bundle.min.js, which includes Popper.js.

Include popper.min.js along with hummingbird.min.js, if hummingbird.bundle.min.js is not included.

<script src="../path/to/@popperjs/core/dist/umd/popper.min.js"></script>
<script src="../path/to/@hummingbirdui/hummingbird/dist/hummingbird.min.js"></script>