Wrapping and Theming

XMLUI ships with a solid set of core components that cover basic needs. But the React ecosystem offers thousands more: charting libraries, rich-text editors, layout engines, calendars, mapping tools, visualization frameworks. The wrapComponent and wrapCompound functions make all of them available to XMLUI users as extension components that work exactly like core components: declarative, composable, AI-friendly, debuggable, automatable.

The Inspector icon at top right is available throughout this section. Use it to explore traces generated by the wrapped component demos embedded in the playgrounds on these pages.

Level 1: Basic wrapping

Call wrapComponent or wrapCompound with a React component and minimal config. You get three things for free:

Prop forwarding. All props flow through by default -- you document them when you're ready, not because the component breaks without it. When the underlying library upgrades and adds new props, they're immediately available to XMLUI users. Standard HTML attributes like title, aria-label, and tabIndex pass through automatically when the render component spreads ...rest onto its outer element.

Free tracing. Wrapped components emit semantic trace events (value:change, focus:change) with no extra code. The aria-label prop becomes the component's accessible name in traces -- a screenreader announces "Volume, slider, 50" and the trace records value:change didChange Slider [Volume] "53". This unlocks accessibility, semantic traces that AIs can reason about, and regression tests generated from user journeys by trace-tools. Export a trace and hand it to an AI -- it doesn't need to read your source code. The trace is the conversation.

Progressive enhancement. No metadata required upfront -- add it incrementally as the component matures. Simple components wrap in minutes; complex libraries take longer for theming and event mapping, but the wrapper config stays small.

Level 2: Trace enrichment

Level 1's generic tracing works for any value that stringifies cleanly. But some values need special handling.

Built-in: File objects. The generic layer recognizes common types like File and emits meaningful trace labels (report.pdf instead of [object File]) plus metadata that trace-tools can use to generate test code.

Per-component: BigCalendar. For domain-specific events, the render component calls onNativeEvent with structured fields -- the wrapper traces it automatically. This is the pattern for any library with its own event model.

Level 3: Theme bridging

A wrapped component needs to respect the design system. Three strategies, depending on the library:

SCSS variable mapping: Gauge. When the library uses CSS custom properties, assign XMLUI tokens to them in SCSS. Three lines. Zero runtime cost.

Runtime style injection: Calendar. When the library uses class-based CSS, resolve XMLUI tokens at runtime via useTheme() and inject scoped styles.

Option-level theming: ECharts. When the library styles via JavaScript config objects (canvas rendering), merge XMLUI tokens directly into the option.

Level 4: Layout

XMLUI's core layout components -- HStack, VStack, FlowLayout -- handle most needs. But some layouts require algorithms the core doesn't provide. Masonry wraps CSS multi-column layout for content feeds and galleries where items of varying height flow into columns. GridLayout wraps a draggable, resizable dashboard grid for cases where the user needs to rearrange and resize panels.

The ecosystem unlocked

XMLUI provides a solid core that wraps a curated set of React components for most basic needs. And it makes it straightforward for a React developer to wrap components that support a range of advanced uses. Here we show: charting (ECharts), rich-text editing (Tiptap), responsive multi-column layout (Masonry), and dashboard grid layout (GridLayout) -- four very different libraries, all wrapped with the same pattern, all getting prop forwarding, semantic tracing, theming, and extension packaging for free. See Extension packaging for details on how to do the wrapping.

ECharts. One of the most powerful charting libraries available -- time series with zoom, treemaps, donuts, toolbox interactions. Canvas-rendered, with option-level theming and comprehensive native event capture.

Tiptap. A headless rich-text editor built on ProseMirror. Every keystroke and format toggle is semantically classified into trace-friendly native events.

Masonry. CSS multi-column layout for content feeds and galleries. Items of varying height flow into responsive columns -- no third-party dependency, just a lightweight wrapper around the browser's native column algorithm.

GridLayout. Draggable, resizable dashboard layout built on react-grid-layout. Users can rearrange and resize cards, while XMLUI still provides the surrounding declarative structure. All of these ship as independent extension packages. Apps include only the components they need. See Extension packaging for details.