@hummingbirdui/hummingbird

v1.1.1

Published

a month ago

An open-source system designed for rapid development, without sacrificing the granular control of utility-first CSS.

The most sensible component system for Tailwind.

downloads npm license

Documentation

Comprehensive documentation is available at hbui.dev.

Getting started

Hummingbird is a fast, lightweight UI library built on top of Tailwind CSS utility classes. Write cleaner HTML, customize with utilities, and bring your project to life with interactive, accessible components. You can:

Use it as a CSS library
Import individual JS components (like Modal, Dropdowns, etc.)
Integrate with React, Vue, Angular, Astro, or any modern JS framework

Installation

1. Install Tailwind CSS

Ensure you have a project set up with Tailwind CSS. If you haven't set up Tailwind CSS yet, follow the official installation guide.

2. Install Hummingbird

Install Hummingbird via your preferred package manager:

# Using npm
npm install @hummingbirdui/hummingbird

# Using yarn
yarn add @hummingbirdui/hummingbird

3. Import CSS

Import Hummingbird styles in your main CSS file (e.g., styles.css).

@import "tailwindcss";
@import "@hummingbirdui/hummingbird";

4. Initialize JS plugins

Include Hummingbird JavaScript at the end of your HTML body.

<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';

Optimization

To reduce the final bundle size, you can import only the specific JavaScript plugins you need.

The below example 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();
});

TypeScript support

Hummingbird includes TypeScript definitions for all components. If you're using TypeScript, you can import Hummingbird plugins with their types.

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 your 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 your 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.

Include using CDN

CDN is a fast and easy way to include Hummingbird in a project.

Play CDN

Use the Play CDN to try Hummingbird in the browser without any build step. The Play CDN is designed for development purposes only, and is not intended for production.

Add the Play CDN script tag to the <head> of your HTML file, and start using Hummingbird’s and Tailwind’s classes to style the content.

<script src="https://cdn.jsdelivr.net/npm/@hummingbirdui/[email protected]/dist/index.global.js"></script>

CDN Script

And include the following JavaScript before the end of the <body> tag for interactive components.

<script src="https://cdn.jsdelivr.net/npm/@hummingbirdui/[email protected]/dist/hummingbird.bundle.min.js"></script>

Supported frameworks

| Framework | Supported | | --------- | --------- | | React | ✅ | | Next.js | ✅ | | Laravel | ✅ | | Vue | ✅ | | Nuxt.js | ✅ | | Angular | ✅ | | Svelte | ✅ | | Astro | ✅ | | Gatsby | ✅ | | Django | ✅ |

License

This project is licensed under the MIT License.

Contribution guidelines

To contribute code:

Fork the repository to your own GitHub account.

Clone your fork locally:

git clone https://github.com/your-username/hummingbird.git
cd hummingbird

Install dependencies:
```
npm install
```
Start the development server: This will start the documentation site locally, allowing you to see changes in real-time.
```
npm start
```
The site will typically be available at http://localhost:4321 (or another port if 4321 is busy).
Create a new branch for your feature or bug fix:
```
git checkout -b feature-or-bugfix-name
```
Make your changes:
- If modifying the library, work in src/.
- If updating documentation, work in apps/.
Build the project (optional but recommended before committing): To ensure everything builds correctly:
```
npm run build:npm
```

Commit your changes:

git commit -m "Your descriptive commit message"

Push your changes to your fork:
```
git push origin feature-or-bugfix-name
```
Open a pull request against the main branch.

Meet the team

Meet the core team behind Hummingbird:

Contributors

Thanks goes to these amazing people: