Version v2.2.1 Size 123.7 KB gzip
ore
orbit
forge
keymapWhy Refine?
Every project needs UI primitives. Refine provides accessible web components that work natively anywhere HTML is rendered—no framework required.
<!-- Before — roll your own button with ARIA -->
<button class="btn btn-primary" role="button" aria-pressed="false" tabindex="0">
<span class="btn-spinner" aria-hidden="true"></span>
Save
</button>
<!-- After — Refine -->
<ore-button variant="primary" loading>Save</ore-button>| Feature | Refine | Shoelace | Material Web |
|---|---|---|---|
| Bundle size | 123.7 KB | ~145 kB | ~200 kB |
| Built with | Ore | Lit | Lit |
| Accessible | WCAG AA | WCAG AA | WCAG AA |
| Framework agnostic |
Use Refine when you want accessible web components that match the Vielzeug design system without a heavy framework dependency.
Consider Shoelace or Material Web if your team is already standardized on those ecosystems and you need their established component catalogs.
Installation
pnpm add @vielzeug/refinenpm install @vielzeug/refineyarn add @vielzeug/refineQuick Start
// 1. Import global styles once
import '@vielzeug/refine/fouc.css'; // Hide unupgraded custom elements until first paint
import '@vielzeug/refine/tokens.css'; // Tokens, animations, cascade layers
// 2. Register only the elements you need
import '@vielzeug/refine/button';
import '@vielzeug/refine/input';
import '@vielzeug/refine/card';<ore-button variant="solid" color="primary">Save</ore-button>
<ore-input label="Email" type="email" required></ore-input>
<ore-card padding="lg">
<span slot="header">Account</span>
<p>Card content goes here.</p>
</ore-card>CDN / Vanilla HTML
Use the self-contained IIFE bundle to load Refine directly from a CDN in any HTML page — no build step required:
<!-- 1. Styles -->
<link rel="stylesheet" href="https://unpkg.com/@vielzeug/refine/dist/styles/fouc.css" />
<link rel="stylesheet" href="https://unpkg.com/@vielzeug/refine/dist/styles/tokens.css" />
<!-- 2. All components (IIFE — registers global Refine namespace) -->
<script src="https://unpkg.com/@vielzeug/refine/dist/refine.iife.js"></script>For bundler-based projects that still want a CDN URL, use the ESM bundle via an import map:
<script type="importmap">
{
"imports": {
"@vielzeug/refine": "https://esm.sh/@vielzeug/refine",
"@vielzeug/refine/button": "https://esm.sh/@vielzeug/refine/button",
"@vielzeug/refine/input": "https://esm.sh/@vielzeug/refine/input"
}
}
</script>
<script type="module">
import '@vielzeug/refine/button';
import '@vielzeug/refine/input';
</script>Package Entry Points
| Import | Purpose |
|---|---|
@vielzeug/refine/fouc.css | FOUC suppression for unupgraded custom elements |
@vielzeug/refine/tokens.css | Global design tokens and cascade layers |
@vielzeug/refine/styles/preflight.css | Optional browser-default reset (includes FOUC suppression) |
Component registration happens through side-effect imports such as @vielzeug/refine/button and @vielzeug/refine/dialog.
Components
Content: ore-avatar, ore-avatar-group, ore-breadcrumb, ore-card, ore-carousel, ore-carousel-slide, ore-chat-message, ore-icon, ore-list, ore-list-item, ore-marquee, ore-pagination, ore-separator, ore-step, ore-stepper, ore-table, ore-text
Disclosure: ore-accordion, ore-accordion-item, ore-tabs, ore-tab-item, ore-tab-panel
Feedback: ore-alert, ore-async, ore-badge, ore-chip, ore-password-strength, ore-progress, ore-skeleton, ore-toast, ore-typing-indicator
Inputs: ore-button, ore-button-group, ore-calendar, ore-checkbox, ore-checkbox-group, ore-column, ore-combobox, ore-datagrid, ore-date-picker, ore-file-input, ore-input, ore-message-composer, ore-number-input, ore-otp-input, ore-radio, ore-radio-group, ore-rating, ore-select, ore-slider, ore-switch, ore-textarea, ore-time-picker
Layout: ore-box, ore-grid, ore-grid-item, ore-navbar, ore-sidebar
Overlay: ore-command-palette, ore-command-palette-item, ore-dialog, ore-drawer, ore-menu, ore-popover, ore-tooltip
Features
- Accessible — keyboard navigation, ARIA wiring, and focus management across interactive components
- Themeable — global tokens plus component-level CSS custom properties
- Framework agnostic — works anywhere HTML can be rendered
- Tree-shakeable — import only the component entry points you register
- Comprehensive surface — inputs, content, disclosure, feedback, layout, and overlay primitives
- Zero runtime deps — 123.7 KB gzipped
Prerequisites
- Browser runtime with Custom Elements support.
- Import
@vielzeug/refine/fouc.cssand@vielzeug/refine/tokens.cssbefore rendering components. - For SSR, render placeholders server-side and hydrate components only on the client.