Render OpenAI ChatKit widget JSON in any web page with a single function call.
Pass a ChatKit widget payload directly to render() and it displays. No ChatKit dependency, no framework lock-in.
npm install @swis/genui-widgetsThe standalone bundle includes Vue and injects CSS automatically.
<div id="widget"></div>
<script src="/dist/genui-widgets.js"></script>
<script>
GenUIWidgets.render(
document.getElementById('widget'),
chatKitPayload,
{ format: 'chatkit' }
);
</script>import { render } from '@swisnl/genui-widgets';
import '@swisnl/genui-widgets/styles';
const container = document.getElementById('widget');
render(container, chatKitPayload, { format: 'chatkit' });
container.addEventListener('genui-action', (e) => {
const { action, payload, formData } = e.detail;
console.log('Action:', action); // { type: 'submit', payload: { ... } }
console.log('Payload:', payload); // shortcut for action.payload
console.log('Form:', formData); // { name: 'John', email: 'john@example.com' }
// Register async work — buttons stay in loading state until resolved
e.detail.waitUntil(
fetch('/api/handle', { body: JSON.stringify({ action, formData }) })
);
// Optionally stop other listeners from running
// e.stopImmediatePropagation();
});Templates can be Jinja strings that resolve to widget JSON at render time:
render(container, `{"type":"Card","children":[{"type":"Title","value":{{ title | tojson }}}]}`, {
templateContext: { title: 'Hello' },
});Extract the template from a .widget file and pass it directly to render():
import { extractTemplateFromWidgetFile, render } from '@swisnl/genui-widgets';
const template = extractTemplateFromWidgetFile(await file.text());
render(container, template);That's it. Pass the raw payload from the OpenAI response and the widget renders.
<script setup lang="ts">
import { DynamicWidget, fromChatKit } from '@swisnl/genui-widgets';
import type { ActionEventDetail } from '@swisnl/genui-widgets';
import '@swisnl/genui-widgets/styles';
const template = fromChatKit(chatKitPayload);
function handleAction(e: CustomEvent<ActionEventDetail>) {
console.log('Action:', e.detail.action);
}
</script>
<template>
<div @genui-action="handleAction">
<DynamicWidget :template="template" />
</div>
</template>render() returns an instance you can update or clean up:
const widget = render(container, chatKitPayload, { format: 'chatkit' });
// Swap in a new payload
widget.update(newPayload);
// Clean up
widget.destroy();Widgets are styled through --genui-* CSS custom properties, all scoped to the .genui-widget-root container element. The library ships two ready-made themes and exposes the full API for custom themes.
import { defaultTheme, darkTheme, render } from '@swisnl/genui-widgets';
// Light (default — applied automatically when no theme is passed)
render(container, payload, { theme: defaultTheme });
// Dark
render(container, payload, { theme: darkTheme });Because all tokens are plain CSS custom properties on .genui-widget-root, you can override them directly in a stylesheet without touching JavaScript at all:
/* Target all widget roots on the page */
.genui-widget-root {
--genui-surface: #f8f4ff;
--genui-background: #f8f4ff;
--genui-text-primary: #1a0040;
--genui-primary-60: #7c3aed;
--genui-primary-70: #6d28d9;
--genui-border-default: #e2e8f0;
--genui-base-size: 0.9rem;
}
/* Or scope overrides to a specific container */
#my-widget .genui-widget-root {
--genui-surface: #1e1e2e;
--genui-text-primary: #cdd6f4;
}Use createTheme() to merge overrides on top of a base theme:
import { createTheme, defaultTheme, render } from '@swisnl/genui-widgets';
render(container, payload, {
theme: createTheme(defaultTheme, {
surface: '#f8f4ff',
background: '#f8f4ff',
textPrimary: '#1a0040',
palettes: {
primary: { 60: '#7c3aed', 70: '#6d28d9' },
},
}),
});Each semantic color (primary, secondary, success, danger, warning, info, discovery, caution) exposes ten lightness steps (5 → 90) as CSS variables:
--genui-primary-60 /* hex value */
--genui-primary-60-rgb /* "R, G, B" for alpha compositing */
Override individual steps without replacing the whole palette:
createTheme(defaultTheme, {
palettes: {
primary: { 60: '#2563eb', 70: '#1d4ed8' },
success: { 50: '#10b981' },
},
});Use the overrides escape hatch to set any --genui-* variable directly:
createTheme(defaultTheme, {
overrides: {
'base-size': '0.9rem',
'--genui-border-default': '#e2e8f0',
},
});Keys are automatically prefixed with --genui- when not already prefixed.
<script setup lang="ts">
import { ref } from 'vue';
import { useTheme, darkTheme } from '@swisnl/genui-widgets';
const container = ref<HTMLElement | null>(null);
const { theme } = useTheme(container, darkTheme);
// Reactively update any token — the container updates automatically
theme.value = { ...theme.value, surface: '#1a1a2e' };
</script>
<template>
<div ref="container">
<DynamicWidget :template="widget" />
</div>
</template>import { applyTheme, createTheme, defaultTheme } from '@swisnl/genui-widgets';
applyTheme(document.getElementById('widget'), createTheme(defaultTheme, {
textPrimary: '#1a0040',
}));const widget = render(container, payload, { format: 'chatkit' });
widget.setTheme(darkTheme);Box Card Button Text Title Markdown Image Form Input Textarea Select Checkbox RadioGroup DatePicker Badge ListView ListViewItem Divider Spacer Row Col Label Caption Icon
npm install
npm run demo # run the demo
npm run build # build both outputs
npm run lint
npm run typecheck
npm test
npm run test:visual
npm run test:visual:update # refresh visual baselines
npm run test:visual:playwright-image
npm run test:visual:update:playwright-image # refresh Linux baselines in the CI imageVisual baselines are stored per OS with prefixes like macos- and linux-. If you need to refresh the screenshots used by GitHub Actions, run the Playwright image update command so the baselines are regenerated inside mcr.microsoft.com/playwright:v1.58.2-noble.
| File | Description |
|---|---|
dist/genui-widgets.esm.js |
ESM build for bundlers |
dist/genui-widgets.css |
Stylesheet for ESM consumers |
dist/genui-widgets.js |
Self-contained browser bundle with CSS injection |
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
This package is open-sourced software licensed under the MIT license.
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
SWIS is a web agency from Leiden, the Netherlands. We love working with open source software.