# XWUI - Complete Reference for AI Assistants > Copy-paste this entire file into Claude, ChatGPT, Gemini, or any LLM to get accurate help > building with XWUI. Last updated: 2025. Version: 1.0.8. Website: https://xwui.dev/ --- ## What is XWUI? XWUI is a framework-agnostic web component library by eXonware. It ships 1,300+ components as standard HTML custom elements (``, ``, etc.). Key characteristics: - **Zero framework dependency** - works in React, Vue, Angular, Svelte, htmx, Alpine, or plain HTML - **No build step required** - drop one `

``` ### Method 2: bundler via import map / CDN (npm NOT yet available) **XWUI is not yet published to npm.** Do NOT install any package named `xwui` or `@exonware/xwui` from the public registry today - nothing currently there is XWUI. npm publication is planned: the free basic tier as `@exonware/xwui`; licensed tiers ship separately via a private registry. Until then, bare-specifier imports of the free tier work through an import map: ```html ``` ```ts // Import individual free-tier component classes: import { XWUIButton, XWUIInputText } from '@exonware/xwui/basic'; ``` ### Method 3: Direct CDN ESM import (type="module") ```html ``` --- ## Loader - smart setup The loader (`esm/loader.js` or `cdn/loader.min.js`) is the easiest way to use XWUI. It handles: - Auto-detecting its own URL and setting the base path - Injecting all required CSS stylesheets - Watching the DOM for `xwui-*` elements and lazy-loading their tier - Exposing `window.XWUI` for imperative use ### Loader configure() API Call `XWUI.configure(config)` at any time - before or after init. Only supply the keys you want to change. ```ts XWUI.configure({ mode?: 'full' | 'tier' | 'component', // Loading strategy. Default: 'tier' min?: boolean, // Use cdn/*.min.js (IIFE). Default: false (use ESM) baseUrl?: string, // Override auto-detected base URL (must end with '/') styles?: boolean, // Inject XWUI CSS on init. Default: true theme?: 'light' | 'dark' | 'auto', // Initial theme. Default: 'auto' version?: string, // Path segment for versioned URLs. E.g. 'v1.0.8' }); ``` #### Option details `mode`: - `'tier'` (default) - watches DOM, loads the tier bundle for each unique tier seen. `` → loads `basic.js`; `` → loads `super.js` - `'component'` - loads one file per custom element tag, on demand. `` → loads `esm/components/XWUIButton.js` - `'full'` - loads the entire library upfront (`xwui.js`). No lazy loading. `min`: - `false` (default) - resolves URLs to `esm/*.js` (ES modules, tree-shakeable) - `true` - resolves URLs to `cdn/*.min.js` (IIFE bundles, no module system needed) `version`: - Inserts a version segment between base and tier paths. - E.g. `XWUI.configure({ version: 'v1.0.8' })` → loads from `BASE/v1.0.8/esm/basic.js` ### Loading pattern examples ```html ``` --- ## Imperative API (window.XWUI) The `window.XWUI` object is available after the loader runs. ```ts // Load a tier and get all its exports const basicMod = await XWUI.load('basic'); // Get a component class by name (loads the tier automatically) const XWUIButton = await XWUI.get('XWUIButton'); new XWUIButton(document.getElementById('app'), { text: 'Click Me' }); // Create a component with a simplified shorthand const btn = await XWUI.create( 'xwui-button', // tag name OR class name ('XWUIButton') 'Click Me', // data (string = text for simple components) { size: 'lg' }, // conf_comp (optional component config) '#app' // container (selector, element, or omit to append to body) ); // Read current base URL console.log(XWUI.base); // e.g. 'https://xwui.dev/' // Check what's loaded console.log([...XWUI.loaded]); // Set of loaded tier keys ``` --- ## Component instantiation pattern Every XWUI component has the same constructor signature: ```ts new XWUI(container: HTMLElement, data: DataShape, conf_comp?: ConfCompShape) ``` - `container` - the DOM element to render into - `data` - the component's content/data (shape varies per component - see examples below) - `conf_comp` - optional component-level configuration (appearance, behavior overrides) ```ts // Example: button new XWUIButton(container, { text: 'Save', variant: 'primary', size: 'md' }); // Example: input new XWUIInputText(container, { value: '', label: 'Email', placeholder: 'user@example.com' }); // Example: spreadsheet new XWUISpreadsheet(container, { rows: 1000, cols: 26, data: { 'A1': 'Hello', 'B1': '=A1' } }); // Example: shell app new XWUIShellApp(container, { title: 'My App', nav: [ { id: 'home', label: 'Home', icon: 'home' }, { id: 'settings', label: 'Settings', icon: 'settings' } ] }); ``` --- ## Tier dependency chain ``` super → power → basic → input chart → basic game → basic industry → basic (peer - does NOT chain into super/game) ``` When using the loader, dependencies are resolved automatically. When importing manually, always import in order (input → basic → power → super). --- ## Tier 1: Input (~80 components) All form input components. Tag prefix pattern: `xwui-input-*` and legacy short names. ```html

``` Full input tag list: xwui-autocomplete, xwui-button, xwui-button-action, xwui-button-copy, xwui-button-f-a-b, xwui-button-group, xwui-button-icon, xwui-button-speech-to-text, xwui-calendar, xwui-cascader, xwui-checkbox, xwui-color-picker, xwui-copy-button, xwui-date-picker, xwui-date-range-picker, xwui-duration-picker, xwui-field, xwui-filters, xwui-form, xwui-form-field, xwui-input, xwui-input-autocomplete, xwui-input-cascader, xwui-input-checkbox, xwui-input-color, xwui-input-color-picker, xwui-input-date, xwui-input-date-picker, xwui-input-date-range, xwui-input-date-range-picker, xwui-input-dimensions, xwui-input-duration, xwui-input-duration-picker, xwui-input-duration-range, xwui-input-duration-range-picker, xwui-input-emoji, xwui-input-emoji-picker, xwui-input-group, xwui-input-icon, xwui-input-icon-picker, xwui-input-json, xwui-input-knob, xwui-input-location, xwui-input-mentions, xwui-input-monetary, xwui-input-multi-select, xwui-input-native-select, xwui-input-number, xwui-input-o-t-p, xwui-input-paragraph, xwui-input-password, xwui-input-phone, xwui-input-picker, xwui-input-radio-group, xwui-input-range-slider, xwui-input-rating, xwui-input-recurrence-picker, xwui-input-segmented-control, xwui-input-select, xwui-input-signature-pad, xwui-input-slider, xwui-input-switch, xwui-input-text, xwui-input-textarea, xwui-input-time, xwui-input-time-picker, xwui-input-time-range, xwui-input-time-range-picker, xwui-input-toggle-group, xwui-input-transfer-list, xwui-input-tree-select, xwui-input-upload, xwui-input-weight, xwui-mentions, xwui-multi-select, xwui-native-select, xwui-picker, xwui-picker-color, xwui-picker-date, xwui-picker-date-range, xwui-picker-time, xwui-quick-actions, xwui-quick-create, xwui-radio-group, xwui-range-slider, xwui-rating, xwui-recurrence-picker, xwui-search, xwui-segmented-control, xwui-select, xwui-signature-pad, xwui-slider, xwui-split-button, xwui-style-selector, xwui-style-switch, xwui-style-toggle, xwui-switch, xwui-task-template-selector, xwui-textarea, xwui-time-picker, xwui-toggle-group, xwui-transfer-list, xwui-tree-select, xwui-upload --- ## Tier 2: Basic (~300 components = input + display + feedback + navigation + behavior + layout) ### Display ```html

``` ### Feedback ```html

Are you sure?

``` ### Navigation ```html

``` ### Behavior (non-visual, functional wrappers) ```html

``` ### Layout ```html

``` --- ## Tier 3: Power Requires: basic tier loaded first. ```html

const x = 42;

Left

Right

``` Full power tag list: xwui-shell-app, xwui-shell-page, xwui-auth-blocks, xwui-auth-forgot-password, xwui-auth-otp, xwui-auth-sign-in, xwui-auth-sign-in-mobile, xwui-auth-sign-out, xwui-auth-sign-up, xwui-auth-unlock, xwui-change-diff-viewer, xwui-chart, xwui-chart-area, xwui-chart-bar, xwui-chart-blocks, xwui-chart-bubble, xwui-chart-distribution, xwui-chart-line, xwui-chart-scatter, xwui-code-block, xwui-command, xwui-component-property-form, xwui-console, xwui-data-grid, xwui-debug-toolbar, xwui-diff-editor, xwui-dynamic-field-renderer, xwui-item-group, xwui-organization-chart, xwui-previewer, xwui-resizable-panel, xwui-rich-text-editor, xwui-sortable-list, xwui-viewport-2d, xwui-viewport-3d, xwui-wizard --- ## Tier 4: Super Requires: power → basic tier. Full-application-level components. ```html

``` Full super tag list: xwui-approval-workflow, xwui-audio-editor, xwui-audio-player, xwui-audio-recorder, xwui-dependency-visualizer, xwui-diagram, xwui-form-editor, xwui-form-master, xwui-gallery-editor, xwui-gallery-master, xwui-gallery-viewer, xwui-gantt-chart, xwui-kanban-board, xwui-pdf-viewer, xwui-photo-editor, xwui-pivot-table, xwui-portfolio-dashboard, xwui-resource-allocation-chart, xwui-script-editor, xwui-spreadsheet, xwui-time-tracker, xwui-video-editor, xwui-video-player, xwui-video-recorder, xwui-workflow --- ## Tier 5: Chart (dedicated chart tier) Requires: basic. High-performance charting separate from the power tier charts. ```html

``` --- ## Tier 6: Game All game component tags start with `xwui-game-`. Requires: basic tier. ```html

``` --- ## Industry tier Vertical-specific component sets. Each domain is a separate bundle. Requires: basic tier (peer - does NOT chain into super/game). ```html ``` Bare-specifier form (once npm publication lands; industry is a licensed tier): ```ts import '@exonware/xwui/industry/accounting'; import '@exonware/xwui/industry/crm'; import '@exonware/xwui/industry/hr'; import '@exonware/xwui/industry/broadcast'; ``` --- ## Theme system XWUI uses CSS custom properties controlled by HTML attributes on ``. The loader injects the appropriate CSS files automatically. ```html data-accent="blue" data-style="modern" data-roundness="rounded" data-font="inter" data-brand="xwui" > ``` ### Switch theme at runtime ```ts document.documentElement.setAttribute('data-theme', 'dark'); document.documentElement.setAttribute('data-accent', 'purple'); ``` ### CSS custom properties XWUI exposes a token system. Key variables: ```css /* Colors */ --color-primary /* brand primary */ --color-surface /* card/panel background */ --color-background /* page background */ --text-primary /* main text */ --text-secondary /* secondary text */ --text-muted /* muted/placeholder text */ /* Spacing */ --spacing-xs /* 4px */ --spacing-sm /* 8px */ --spacing-md /* 16px */ --spacing-lg /* 24px */ --spacing-xl /* 32px */ --spacing-2xl /* 48px */ /* Typography */ --font-family-base --font-size-sm /* 12px */ --font-size-md /* 14px */ --font-size-lg /* 16px */ --font-size-xl /* 20px */ /* Borders */ --radius-sm /* small radius */ --radius-md /* medium radius */ --radius-lg /* large radius */ --radius-full /* pill / circle */ /* Shadows */ --shadow-sm --shadow-md --shadow-lg ``` --- ## Framework integration XWUI custom elements work natively with all frameworks. ### React ```tsx // React 19+ has full custom element support. // For older React, use the @exonware/xwui-react wrapper (if available). import '@exonware/xwui/basic'; function MyForm() { return (

console.log(e.detail)} /> console.log('clicked')} />

); } // TypeScript: add to your declarations to avoid unknown element errors declare global { namespace JSX { interface IntrinsicElements { 'xwui-button': React.HTMLAttributes & { text?: string; variant?: string }; 'xwui-input-text': React.HTMLAttributes & { label?: string; value?: string }; // … add more as needed, or use a global wildcard [key: `xwui-${string}`]: React.HTMLAttributes & Record; } } } ``` ### Vue 3 ```html ``` ```ts // vite.config.ts export default defineConfig({ plugins: [vue({ template: { compilerOptions: { isCustomElement: tag => tag.startsWith('xwui-') } } })] }); ``` ### Angular ```ts // app.module.ts import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core'; import '@exonware/xwui/basic'; @NgModule({ schemas: [CUSTOM_ELEMENTS_SCHEMA], }) export class AppModule {} ``` ### Plain HTML / htmx / Alpine ```html

``` --- ## Events XWUI components fire standard `CustomEvent`s. The event detail contains the updated value. ```ts // Listen for component events document.querySelector('xwui-input-text').addEventListener('change', (e) => { console.log(e.detail); // { value: 'new value' } }); document.querySelector('xwui-button').addEventListener('click', (e) => { console.log('button clicked'); }); document.querySelector('xwui-spreadsheet').addEventListener('cellchange', (e) => { console.log(e.detail); // { cellId: 'A1', value: 'new value', formula: '=B1+1' } }); ``` --- ## TypeScript types ```ts // Types ship in dist/types/ on the CDN (npm package not yet published - see Installation). // With the import map from "Method 2" plus a matching "@exonware/xwui/types/" entry: import type { XWUIButtonData, XWUIInputTextData } from '@exonware/xwui/types/basic'; import type { XWUISpreadsheetData } from '@exonware/xwui/types/super'; ``` --- ## Common recipes ### Recipe 1: Login page ```html ``` ### Recipe 2: Dashboard shell with sidebar ```html

``` ### Recipe 3: Data table with filters ```html

``` ### Recipe 4: Spreadsheet with initial data ```html

``` ### Recipe 5: Form with validation ```html

``` ### Recipe 6: Upload and preview files ```html

``` --- ## Loading strategy comparison | Strategy | Initial JS | HTTP requests | Best for | |----------|-----------|---------------|----------| | `mode:'tier'` (default) | ~input bundle | 1 per tier encountered | Most web apps | | `mode:'component'` | ~0 | 1 per unique component | Micro-frontends, CMS pages | | `mode:'full'` | all tiers | 1 | Dashboards, intranets | | Direct ` ``` --- ## Version pinning Pin a specific version to prevent breaking changes from auto-updating: ```html ``` --- ## Quick tag → tier lookup Use this to know which tier script a component needs: | Tag prefix | Tier | Script | |------------|------|--------| | `xwui-button*`, `xwui-input-*`, `xwui-form*`, `xwui-search`, `xwui-select`, `xwui-slider`, … | input | `esm/input.js` | | `xwui-card`, `xwui-table`, `xwui-list`, `xwui-accordion`, `xwui-nav-*`, `xwui-overlay-*`, `xwui-progress-*`, `xwui-display-*`, `xwui-feedback-*`, `xwui-layout*`, `xwui-stack`, `xwui-flex`, `xwui-grid`, … | basic | `esm/basic.js` | | `xwui-shell-*`, `xwui-auth-*`, `xwui-data-grid`, `xwui-rich-text-editor`, `xwui-code-block`, `xwui-chart*`, `xwui-wizard`, `xwui-command`, … | power | `esm/power.js` | | `xwui-spreadsheet`, `xwui-kanban-board`, `xwui-gantt-chart`, `xwui-diagram`, `xwui-form-editor`, `xwui-video-*`, `xwui-audio-*`, `xwui-pdf-viewer`, `xwui-pivot-table`, … | super | `esm/super.js` | | `xwui-game-*` | game | `esm/game.js` | | `xwui-chart-line`, `xwui-chart-bar`, `xwui-chart-area`, … | chart | `esm/chart.js` | The loader resolves this automatically - this table is only needed for manual imports. --- ## Troubleshooting **Components not rendering / undefined custom element:** - Check that the correct tier bundle is loaded (use loader or import the right tier) - The tier must be fully loaded before the element is created - Use `await customElements.whenDefined('xwui-button')` before accessing the element **CSS not applied:** - Ensure styles are loaded: `XWUI.configure({ styles: true })` (default) - Or add `` - the loader reads this to select the right CSS **Wrong base URL (CORS / 404 errors for CSS/JS files):** - Set `XWUI.configure({ baseUrl: 'https://yourcdn.com/xwui/' })` to override auto-detection **Custom elements not defined in SSR/Node:** - XWUI is browser-only. Skip import during SSR; hydrate client-side. **TypeScript "unknown element" errors:** - Add `[key: \`xwui-\${string}\`]: any` to your JSX intrinsic elements declaration. --- *End of XWUI full reference. For updates: https://xwui.dev/llms-full.txt* *Source: https://xwui.dev/ | npm: @exonware/xwui | GitHub: github.com/exonware/xwui*