@bquery/ui is a production-grade component library built with native Web Components, Shadow DOM, and TypeScript 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.
- 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
- Tree-shakeable ESM exports with per-component imports
- CDN-ready root bundles for ES modules, UMD, and IIFE delivery
- Built-in dark mode, i18n, and event-driven APIs
The current library covers the core component categories developers expect from modern UI libraries:
| Category | Components |
|---|---|
| Actions | Button, Icon Button |
| Forms | Input, Textarea, Select, Checkbox, Radio, Switch, Slider, Chip |
| Navigation | Tabs, Accordion, Breadcrumbs, Pagination |
| Data Display | Card, Badge, Avatar, Table, Divider, Empty State, Stat Card |
| Feedback | Alert, Progress, Spinner, Skeleton, Tooltip, Toast |
| Overlays | Dialog, Drawer |
For the full catalog and feature coverage, see docs/components/index.md.
npm install @bquery/uiimport '@bquery/ui';<bq-button variant="primary">Save changes</bq-button>
<bq-input label="Email" type="email" placeholder="you@example.com"></bq-input>
<bq-alert variant="success" title="Profile updated">
Your changes have been saved successfully.
</bq-alert><!-- ESM -->
<script type="module">
import 'https://cdn.jsdelivr.net/npm/@bquery/ui@1.1.0/dist/index.js';
</script>
<!-- UMD -->
<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.1.0/dist/index.umd.js"></script>
<!-- IIFE -->
<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.1.0/dist/index.iife.js"></script>The UMD and IIFE bundles expose the library on window.BQueryUI.
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';This import-based registration update changes how consumers integrate @bquery/ui.
- Importing
@bquery/uinow 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
registerBqButtonare no longer re-exported from@bquery/ui. registerAll()remains available only as a deprecated compatibility shim.- 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';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.
- Semantic roles and ARIA attributes
- Keyboard interactions for tabs, dialogs, accordions, sliders, and other interactive controls
- Focus trapping and focus restoration for overlays
aria-livesupport for alerts and toasts
- CSS custom properties for colors, spacing, typography, radius, shadows, motion, and z-index
- Light and dark themes
::part()support for targeted customization
- User-facing strings run through the library i18n system
- Locale overrides supported through exported utilities
- TypeScript typings included
- Structured
bq-*custom events - Consistent slot and part APIs
- Storybook stories and VitePress docs
- Getting started
- Installation
- Framework integration
- Theming
- Accessibility
- Component catalog
- Button reference
- Input reference
- Card reference
bun install --frozen-lockfile
npm run devIf 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.
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 suitesrc/
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
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.