@bquery/ui
@bquery/ui is a production-grade component library built with native Web Components, Shadow DOM, and TypeScript on top of @bquery/bquery for the bQuery ecosystem.
It is designed to give teams the kind of component coverage, polish, accessibility, and framework interoperability that developers expect from established libraries such as Material UI, Vuetify, Angular Material, and modern Vue/Svelte UI kits—while staying framework-agnostic and standards-based.
Highlights
- Reusable UI components spanning actions, forms, navigation, data display, overlays, and feedback
- Framework-agnostic usage in plain HTML, React, Vue, Angular, Svelte, and other Custom Element-capable runtimes
- Accessible by default with keyboard support, ARIA roles, focus management, and screen reader announcements
- Themeable via design tokens and CSS custom properties, switchable from the document in every browser
- A built-in icon set rendered as CSS masks, so glyphs inherit text colour and stay crisp at any size
- Tree-shakeable ESM exports with per-component imports
- Browser-ready UMD and IIFE bundles for direct CDN delivery
- Built-in dark mode, i18n, and event-driven APIs
Component Coverage
The current library covers the core component categories developers expect from modern UI libraries:
| Category | Components |
|---|
| Actions | Button, Icon Button, Button Group, Copy Button |
| Forms | Input, Number Input, Textarea, Select, Combobox, Tag Input, Pin Input, Date Picker, Segmented Control, Checkbox, Radio, Switch, Slider, Chip, Rating, File Upload |
| Navigation | Tabs, Accordion, Breadcrumbs, Pagination, Stepper, Tree |
| Data Display | Card, Badge, Avatar, Avatar Group, Table, Divider, Empty State, Stat Card, Timeline, Kbd, Icon, Meter |
| Feedback | Alert, Banner, Progress, Spinner, Skeleton, Tooltip, Toast |
| Overlays | Dialog, Drawer, Dropdown Menu, Popover |
For the full catalog and feature coverage, see docs/components/index.md.
Quick Start
Install
npm install @bquery/ui
If your package manager does not automatically resolve peer dependencies, install @bquery/bquery alongside @bquery/ui.
Import once
import '@bquery/ui';
Use in HTML
<bq-button variant="primary">Save changes</bq-button>
<bq-input label="Email" type="email" placeholder="[email protected]"></bq-input>
<bq-alert variant="success" title="Profile updated">
Your changes have been saved successfully.
</bq-alert>
Use in the browser without a bundler
<!-- UMD -->
<script src="https://cdn.jsdelivr.net/npm/@bquery/[email protected]/dist/index.umd.js"></script>
<!-- IIFE -->
<script src="https://cdn.jsdelivr.net/npm/@bquery/[email protected]/dist/index.iife.js"></script>
The UMD and IIFE bundles register all components on load and expose the library on window.BQueryUI.
For ESM-based app builds, prefer importing @bquery/ui from your bundler or other module-aware build tool.
Current release snapshot
The current release (1.15.0) emphasizes:
- A built-in icon set. Interface glyphs are rendered as CSS masks rather than text characters, so they inherit
currentColor, scale with font-size, and look the same on every platform. Available as <bq-icon> and to your own components through iconCss().
- Dark mode that works in every browser. The scheme now travels through an inherited custom-property channel instead of
:host-context(), which exists only in Chromium — and which, sitting in a selector list, previously took the whole dark theme down with it in Firefox and Safari. data-theme also works on any subtree, not just the root.
- A deeper token layer. Semantic surfaces (
--bq-surface-raised, --bq-surface-overlay), translucent interaction states, per-intent focus rings, a shared control-height scale, and dark-mode elevation.
- Focus that survives a re-render. Rendering replaces the shadow tree; text fields, calendars and tree views now keep focus and the caret across the renders their own interactions cause.
- A larger production-ready catalog. The package spans 49 web components across actions, forms, navigation, data display, feedback, and overlays — including
bq-date-picker, bq-tree, bq-pin-input, bq-meter, bq-copy-button, and bq-icon.
- Aligned docs and browser bundles. Version-pinned CDN snippets, migration guidance, and Storybook/VitePress references target
1.15.0.
Tree-Shakeable Usage
Import only the component entry points you need for the smallest bundle:
import '@bquery/ui/components/button';
import '@bquery/ui/components/input';
import '@bquery/ui/components/dialog';
Migration Notes
This import-based registration update changes how consumers integrate @bquery/ui.
- Importing
@bquery/ui now registers all custom elements as a side effect.
- Importing
@bquery/ui/components/<name> registers only that component through its wrapper entrypoint.
- Legacy root-level component registration helpers such as
registerBqButton are no longer re-exported from @bquery/ui.
- The deprecated
registerAll() named export still exists for backwards compatibility and can be imported from @bquery/ui or explicitly from @bquery/ui/register.
- New code should avoid
registerAll() and rely on import side effects instead.
- Calling
registerAll() without arguments is still accepted for temporary backward compatibility, but it does not perform any additional registration work.
- Passing any legacy options object to
registerAll() continues to emit a warning.
For example, older calls such as registerAll({ prefix: 'ACME' }) now warn because components self-register on import as bq-*.
The supported replacement is importing @bquery/ui once, or only the specific @bquery/ui/components/<name> entrypoints you need.
If you previously imported component registration helpers from the package root, migrate those imports to either:
import '@bquery/ui';
or the specific component entrypoints you need:
import '@bquery/ui/components/button';
import '@bquery/ui/components/input';
Cross-Framework Support
Because the library is built on Web standards, the same components can be used across major frontend frameworks.
| Framework | Integration note |
|---|
| React | Import the library once and subscribe to custom events through refs or wrapper components |
| Vue | Use components directly in templates and listen to bq-* custom events |
| Angular | Enable CUSTOM_ELEMENTS_SCHEMA and use bq-* elements like native controls |
| Svelte | Register once during onMount and bind to custom events with on:bq-* |
| Plain HTML / bQuery | Works out of the box after a single import |
See docs/guide/framework-integration.md for examples.
For migration guidance from older registration patterns, see docs/guide/migration-from-1-1-0.md.
Core Capabilities
Accessibility
- Semantic roles and ARIA attributes
- Keyboard interactions for tabs, dialogs, accordions, sliders, and other interactive controls
- Focus trapping and focus restoration for overlays
aria-live support for alerts and toasts
Theming
- CSS custom properties for colors, spacing, typography, radius, shadows, motion, and z-index
- Semantic surface, interaction, and focus-ring tokens on top of the raw palette
- Light and dark themes, switchable per document or per subtree with
data-theme
::part() support for targeted customization
Icons
- A built-in set of interface glyphs, available as
<bq-icon name="…">
- Rendered through CSS masks, so an icon inherits
currentColor and scales with font-size
iconCss() lets your own components pull in only the glyphs they draw
Internationalization
- User-facing strings run through the library i18n system
- Locale overrides supported through exported utilities
Developer Experience
- TypeScript typings included
- Structured
bq-* custom events
- Consistent slot and part APIs
- Storybook stories and VitePress docs
Documentation
Local Development
bun install --frozen-lockfile
npm run dev
If Bun is not installed globally in your environment, use npx bun install --frozen-lockfile for setup and npx bun test for tests. See AGENT.md for the full non-global Bun workflow.
Available scripts
npm run build # build library + type declarations
npm run build:docs # build VitePress documentation
npm run storybook # run Storybook locally
npm run build:storybook
npm run lint:types # TypeScript type-check
npm run test # Bun test suite
Project Structure
src/
components/ # Web components
tokens/ # design tokens
theme/ # theme helpers and CSS variables
i18n/ # localization utilities
utils/ # shared helpers
docs/ # VitePress documentation
stories/ # Storybook stories
tests/ # component and utility tests
Contributing
Contributions that improve component quality, accessibility, theming, documentation, and cross-framework ergonomics are welcome.
When contributing:
- Keep changes focused and consistent with the existing component patterns.
- Validate type safety, documentation, and affected component behavior.
- Prefer additions that improve accessibility, composability, or API consistency.
- If you are working as an automated coding agent, follow the repository-specific guidance in
AGENT.md, including the canonical Bun workflow.
License
MIT
