# XWUI

> Framework-agnostic web component library - 1,300+ components across nine tiers, works with any framework or no framework at all.

XWUI components are standard custom elements (`<xwui-button>`, `<xwui-input-text>`, etc.).
Drop the loader in your page and every component self-registers. No build step, no framework required.
Works identically in React, Vue, Angular, Svelte, htmx, Alpine, or plain HTML.

Version: 1.0.8 | CDN: https://xwui.dev/ | npm: not yet published (see "npm" below) | Updated: 2026-09-02

## Quick start

```html
<!-- Minimal: one script tag, then use any free-tier xwui-* element -->
<script type="module" src="https://xwui.dev/esm/loader.js"></script>

<xwui-button text="Click Me"></xwui-button>
<xwui-input-text label="Name" placeholder="Enter your name"></xwui-input-text>
<xwui-table></xwui-table>
```

## Three loading modes

The loader supports three strategies. Set via `XWUI.configure()` before or after init.

| Mode | What loads | Best for |
|------|-----------|----------|
| `tier` (default) | Tier bundle when first `xwui-*` tag of that tier is seen | Most apps |
| `component` | One file per custom element, on demand | Minimal payload |
| `full` | Entire library upfront | Internal dashboards |

```html
<!-- Tier mode (default - no configure needed) -->
<script type="module" src="https://xwui.dev/esm/loader.js"></script>

<!-- Component mode: smallest payload -->
<script type="module" src="https://xwui.dev/esm/loader.js"></script>
<script type="module">XWUI.configure({ mode: 'component' });</script>

<!-- Full mode: load everything immediately -->
<script type="module" src="https://xwui.dev/esm/loader.js"></script>
<script type="module">XWUI.configure({ mode: 'full' });</script>
```

## Tiers (9)

Free tier - loads directly from the CDN, no licence needed:
- **basic** (~390 components, includes the **input** sub-tier's 80+ form controls) - cards, lists, tables, avatars, badges, dialogs, toasts, navigation bars, tabs, sidebars, text/number/date/time/color/file inputs, signature, OTP, rating, slider, cascader, mentions, emoji picker, …

Licensed tiers - sealed on the CDN; a licence from https://xwui.dev unlocks them (the loader handles the unlock automatically for licensed sites):
- **dashboard** (~22) - dashboard shells and widgets
- **power** (~65) - app shell, auth flows, rich-text editor, code editor, diff viewer, command palette, wizard, 2D/3D viewports, …
- **chart** (~335) - dedicated chart tier: area, bar, line, scatter, bubble, distribution, blocks
- **super** (~59) - heavy apps: spreadsheet, kanban, gantt, diagram, form builder, gallery, audio/video player/editor/recorder, PDF viewer, pivot table, script editor, …
- **game** (~165) - game UI components (all tags start with `xwui-game-`)
- **gis** (~6) - maps and geo components
- **enterprise** (~1) - commercial-grade sellable surfaces: data grid (XWUIDataGrid, moved from power 2026-09-02), scheduler, tree grid
- **industry** (~290) - vertical-specific sets: accounting, CRM, HR, broadcast, and more

## npm

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 against the CDN:

```html
<script type="importmap">
{ "imports": { "@exonware/xwui/basic": "https://xwui.dev/esm/basic.bundle.js" } }
</script>
<script type="module">
  import { XWUIButton } from '@exonware/xwui/basic';
</script>
```

## Loader configure() API

```ts
XWUI.configure({
  mode?:    'full' | 'tier' | 'component', // default: 'tier'
  min?:     boolean,                        // true = use cdn/*.min.js (IIFE), false = esm (default)
  baseUrl?: string,                         // override auto-detected base URL
  styles?:  boolean,                        // inject CSS on init (default: true)
  theme?:   'light' | 'dark' | 'auto',     // default: 'auto' (follows prefers-color-scheme)
  version?: string,                         // e.g. 'v1.0.8' for versioned CDN paths
});
```

## Imperative API (window.XWUI)

```ts
// Load a tier and get all its exports (licensed tiers require an unlocked licence)
await XWUI.load('basic');

// Get a component class by name (loads the tier automatically)
const XWUITable = await XWUI.get('XWUITable');
new XWUITable(document.getElementById('container'), { columns: ['Name', 'Email'], rows: [] });

// Create a component with a simplified shorthand
const btn = await XWUI.create('xwui-button', 'Click Me', { size: 'lg' }, '#app');
```

## Theme / styling

Set HTML attributes on `<html>` to control the visual style:

```html
<html data-theme="dark" data-accent="blue" data-style="modern" data-roundness="rounded" data-font="inter">
```

## Dist files

| Path | Description |
|------|-------------|
| `esm/loader.js` | Smart loader (recommended entry point) |
| `esm/xwui.js` | Full ESM bundle |
| `esm/basic.js` / `power.js` / `super.js` | Tier bundles |
| `esm/components/*.js` | Per-component ESM files |
| `cdn/*.min.js` | Minified IIFE bundles for `<script>` tags |
| `styles/` | CSS tokens, themes, fonts, icons |
| `types/` | TypeScript `.d.ts` declarations |

## Machine-readable catalog

| URL | What |
|-----|------|
| https://xwui.dev/custom-elements.json | Custom Elements Manifest (CEM v2): every registered element with typed, schema-derived attributes |
| https://xwui.dev/__component_index__.json | Compact index: name, tag, tier, path, description for every custom element |
| https://xwui.dev/schemas/v1/index.json | XWUI Platform Contract: per-component draft-07 JSON Schemas (all 9 tiers) + the xwweb site-from-JSON DSL schema; additive-only within /v1/ |
| https://xwui.dev/design.md | How an AI should design with XWUI: the fetch-schema, validate, render loop |
| https://xwui.dev/docs-index.html | Crawlable index over every per-component markdown doc |
| https://xwui.dev/component-count.md | Counting methodology: 1,329 components vs 1,141 custom elements, per tier |
| https://xwui.dev/changelog.md | Release history |
| https://xwui.dev/demos/ | Per-framework demo apps (React, Vue, Svelte, plain HTML, htmx, ...) |

## MCP server

Query the live catalog directly - list/search components, fetch the real JSON schema and
examples, validate a config BEFORE rendering it:

```json
{ "mcpServers": { "xwui": { "type": "http", "url": "https://xwui.dev/mcp" } } }
```

Tools: list_components, search_components, get_component_schema, get_component_example,
validate_component_config, suggest_import, list_presets, get_llms_txt.

## Full reference

For the complete component list, all configure() options, and copy-paste patterns:
https://xwui.dev/llms-full.txt