Blackstone UI (BUI) is an open-source library of low-level custom elements, full-featured presenters, utility functions, and an application router for building single-page progressive web apps, built with Lit and maintained by Blackstone Publishing.
What is Blackstone UI?
Blackstone UI is a collection of web components built on top of the Lit library, created by Blackstone Publishing for internal production applications. It takes reusable UI component code and provides it as a set of custom elements that can be imported selectively or used together to create a full featured application, plus Node.js server classes for building RESTful APIs. The library runs entirely in the JavaScript ecosystem, works with any framework that supports web components, and is distributed as an npm package.
Key Features
- Progressive scaling — Interface components scale smoothly from desktop to mobile devices without a separate responsive codebase.
- Dark/Light Mode — Built-in theme switching supported across all components in the library.
- Color Themes — Multiple color theme options that work via CSS custom properties.
- Modern async/await structure — The component APIs are designed around async/await style structure for modern JavaScript development.
- Customizable via CSS vars and parts — Shadow DOM encapsulation is paired with CSS custom properties and CSS parts for styling control.
- URL route management — Includes an application router for handling client-side routes in single-page PWAs.
- Node.js server classes — Provides server-side classes for creating RESTful APIs, extending beyond client-side components.
- Interoperable — Custom elements are extensible and can work alongside other frameworks because they follow the Web Components standard.
Who is it for?
BUI is built for JavaScript developers who want to assemble applications from standardized, encapsulated UI components rather than writing markup and styles from scratch. Teams at Blackstone Publishing use it in multiple internal production environments; external developers can use the same library to create single-page apps, dashboards, and PWAs. It also suits full-stack developers who want both client components and Node.js server classes in one toolkit.
What can you do with Blackstone UI?
- Build a full-featured SPA — Combine the presenters, router, and utility functions to create a complete single-page application with routing and themed components.
- Use only a few components — Import a select handful of custom elements into an existing project and get the same look and behavior without adopting the whole library.
- Create a RESTful API — Leverage the included Node.js server classes to build backend endpoints alongside your frontend.
- Prototype with the demo app — Clone the repository, run the Parcel-bundled demo at localhost:1234, and use the documentation site as a reference for how components work together.
How does Blackstone UI work?
Web components in BUI use Shadow DOM for style and DOM encapsulation, CSS custom properties for theming, and CSS parts for targeted styling overrides. To start, install the package directly from the GitHub repository, then import the components you need. The demo can be run locally by installing Parcel globally, cloning the repo, and running npm install and npm start.
Pros and cons
- Pros: Actively developed and used in production at Blackstone Publishing; offers both client-side components and server-side classes; customizable through standards-based CSS features.
- Cons: The library updates frequently, so npm releases may lag behind the latest code and the documentation may not be fully up to date; installation from the GitHub URL is recommended for the latest version.
FAQ
How do I install BUI?
Run npm install https://github.com/kjantzer/bui.git --save to get the latest version directly from GitHub. The package is also available on npm as blackstone-ui, but the README recommends installing from the repository because releases may be infrequent.
Does BUI support dark mode?
Yes, the library includes built-in dark/light mode support that can be toggled across its components.
What is BUI built with?
BUI is built with Lit, the web components library, and uses Shadow DOM and CSS custom properties for encapsulation and theming.
Can I use BUI with other frameworks?
Yes, because BUI is a set of standard web components, it is extensible and interoperable with other frameworks.
