Vue
Installation
Section titled “Installation”npm i @golemui/core @golemui/gui-shared @golemui/vue @golemui/gui-vue @golemui/gui-components --saveVite plugin configuration
Section titled “Vite plugin configuration”<GuiForm> works without any compiler configuration. GolemUI’s default widgets are Lit custom elements (<gui-textinput>, <gui-button>, …), and the component renders them itself. Only a component of your own that places a raw gui-* tag in its template needs the Vue template compiler to leave those tags alone, so they reach the DOM as native custom elements:
import vue from '@vitejs/plugin-vue';
export default defineConfig({ plugins: [ vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('gui-'), }, }, }), ],});Styles
Section titled “Styles”Import the core styles in your application entry point or global stylesheet:
@import '@golemui/gui-components/index.css';<GuiForm> only needs a formDef. The framework’s built-in widget set is loaded automatically, and an empty form renders fine without initial data.
<script setup lang="ts">import { gui } from '@golemui/gui-shared';import { GuiForm } from '@golemui/gui-vue';
const config = { formDef: [gui.inputs.textInput('username', { label: 'Username' })],};</script>
<template> <GuiForm :config="config" /></template><script setup lang="ts">import { GuiForm } from '@golemui/gui-vue';import formDef from './my-form.json';
const config = { formDef };</script>
<template> <GuiForm :config="config" /></template>Adding optional config
Section titled “Adding optional config”Reach for these only when you need them. data prefills the form; customWidgetLoaders is for widgets you’ve built yourself (the framework’s built-ins are merged automatically). Every other config property in the table below follows the same rule — opt in as the form grows.
<script setup lang="ts">import { gui } from '@golemui/gui-shared';import { GuiForm } from '@golemui/gui-vue';import { myCustomWidgets } from './my-custom-widgets';
const config = { formDef: [gui.inputs.textInput('username', { label: 'Username' })], data: { username: 'octocat' }, // optional — initial form data customWidgetLoaders: myCustomWidgets, // optional — only when the form references widgets you've built yourself};</script>
<template> <GuiForm :config="config" /></template><script setup lang="ts">import { GuiForm } from '@golemui/gui-vue';import { myCustomWidgets } from './my-custom-widgets';import formDef from './my-form.json';
const config = { formDef, data: { username: 'octocat' }, // optional — initial form data customWidgetLoaders: myCustomWidgets, // optional — only when the form references widgets you've built yourself};</script>
<template> <GuiForm :config="config" /></template><GuiForm> props
Section titled “<GuiForm> props”All initialization properties are bundled in the required config prop (GuiFormInitConfig):
config property | Type | Description |
|---|---|---|
formDef (required) | FormInput | Programmatic gui.* array or parsed JSON form definition. |
formSelectors | GslSelectorsInput | GSL selector decorators. Programmatic-only. |
formConfig | DxFormConfig | DX engine wiring (loaders, item renderers, dependencies, validateOn, …). Programmatic-only. |
data | Record<string, any> | Initial form data. |
meta | Record<string, any> | Out-of-band metadata you want to thread through events and state. |
customWidgetLoaders | WidgetLoaders<Component<WithWidget>> | Custom widget map; merged with the default Vue widget set. |
itemRenderers | Record<string, VueItemRenderer<any>> | Custom item-renderer map (for dropdown, list, etc.). |
customValidators | CustomValidatorSchemas | Custom validator schemas referenced by validator: { type: 'custom', ... }. |
middlewares | Middleware<State, Action>[] | Store middlewares (logging, persistence, devtools). |
validateOn | ValidateOn | When validation runs: 'eager' (default), 'change', 'blur', 'submit', or an array. |
dependencies | Dependencies | External helpers (e.g. a markdown parser). |
localization | I18nTranslator | Translator implementing the I18nTranslator interface. |
formName | string | Optional form identifier (useful when you have several forms on a page). Recommended for server rendering: keeps the ids identical on both sides. |
expressionPolicy | 'warn' | 'strict' | How strictly the form treats its expressions. Defaults to 'warn'. See Configuration. |
Direct props (outside config):
| Prop | Type | Description |
|---|---|---|
autocomplete | string | Sets the underlying <form> element’s autocomplete attribute. |
form-health-boundary | Component | Component that wraps the form and renders the error UI for an errored FormHealth. Defaults to a red banner. See Configuration. |
The component also emits three events:
| Event | Payload type | Description |
|---|---|---|
@form-event | FormEvent | Fired when a widget fires a wired event. |
@form-submit | FormSubmitEvent | Fired when a submit button is clicked and the whole form passes validation. |
@form-health | FormHealth | Fired when the form’s operational status changes, such as a definition error or a widget that could not be loaded. See Configuration. |
See Configuration for details on each prop, plus the Programmatic-only vs JSON-form notes.
Custom widgets in Vue
Section titled “Custom widgets in Vue”Build your own widgets as Vue SFCs that consume the framework adapter via the useInputWidget, useLayoutWidget, useDisplayWidget, and useActionWidget composables exported from @golemui/vue. The composables expose Ref-typed reactive state (value, errors, isTouched, templateData) and disposal-safe dispatchers; they handle observable cleanup via onScopeDispose automatically. See Extending GolemUI / Widgets for the full walkthrough.
Server-side rendering
Section titled “Server-side rendering”<GuiForm> renders on the server with renderToString and hydrates through createSSRApp: the server emits the Vue layer with the widget props as attributes, and the gui-* elements fill in once the browser upgrades them. Preload the widgets on both sides first. See Vue SSR for the contract and Nuxt for the Nuxt wiring.