balsigergil / bloum

A lightweight yet powerful library of unstyled web components.

Bloum

A lightweight yet powerful library of unstyled web components.

Table of Contents

• 📖 Introduction
• 🚀 Features
• 📦 Installation
• 💻 Usage
• 📋 Documentation
• 📝 Contributing
• ⚖️ License

Introduction

What is Bloum?

Bloum is an open-source library of unstyled web components. The goal of this library is to provide a set of components that can be used in any web project, regardless of the framework or library used. It implements the most common components used in web applications that required a lot of JavaScript to work, like select, tabs, modals, etc.

It is unstyled by default, meaning that it doesn't provide an opinionated design. It is up to you to style the components to fit your needs. However, it comes with a theme that you can use to get started quickly.

Why Bloum?

The goal for this library is not to provide an exhaustive list of components, but rather to provider components that are usually tedious to implement and require a lot of JavaScript to work.

⚠️ Warning: It currently doesn't support virtual DOM libraries like React or Vue.

Features

• 🪶 Lightweight: As an unstyled library, it comes with minimal CSS for you to style the components as you wish.
• 🔍 Accessible: Built with accessibility in mind. It's fully keyboard navigable and ARIA compliant.
• 🌓 Dark mode: Supports dark mode out of the box.
• 📱 Responsive: Works on all modern browsers and devices.
• 📦 No dependencies: Does not depend on any other library or framework.
• 🧪 Tested: End-to-end tests with Playwright.
• 🎨 Theming: Easy to customize and comes with a modern theme to quickly get started.
• 🌈 Modern: Built with the Web Components API.
• 🤹 Versatile: Can be used with any non-(virtual DOM) client-side library like Svelte, Alpine.js or HTMX and can be integrated with Tailwind CSS or Bootstrap.

Components:

• Select
• Modal
• Alert dialog
• Tabs
• Toast
• Accordion / Collapse
• DatePicker / TimePicker / Calendar
• Stepper / Wizard
• Popover
• Tooltip
• DataTable
• Phone input
• Switch
• Color picker

Installation

CDN

You can use the following lines in your head tag to load the latest version of Bloum from a CDN:

<script src="https://unpkg.com/bloum" defer></script>

<!-- include the default unstyled stylesheet -->
<link href="https://unpkg.com/bloum/dist/style.min.css" rel="stylesheet">
<!-- include the modern theme -->
<link href="https://unpkg.com/bloum/dist/modern.min.css" rel="stylesheet">

Package manager

You can install Bloum using your favorite package manager:

# NPM
npm install bloum

# Yarn
yarn add bloum

# Pnpm
pnpm add bloum

# Bun
bun add bloum

Usage

Once installed, you can import the library in your JavaScript project:

import "bloum"

This will register all the components globally.

After that, you can include the default unstyled stylesheet in your JavaScript if you're using a bundler like Vite or Webpack:

import "bloum/dist/style.min.css"

If you want to use an already styled theme, you can include it too:

import "bloum/dist/modern.min.css"

Then, you can use the components in your HTML:

<bl-select name="my-select">
  <div data-value="1">Option 1</div>
  <div data-value="2">Option 2</div>
  <div data-value="3">Option 3</div>
</bl-select>

Documentation

The documentation is available at https://www.bloum.dev.

Contributing

TODO

License

Bloum is MIT licensed © Gil Balsiger