Vue

Installation

npm i @golemui/core @golemui/gui-shared @golemui/vue @golemui/gui-vue --save

Vite plugin configuration

GolemUI’s default widgets are Lit custom elements (<gui-textinput>, <gui-button>, …). Tell the Vue template compiler to leave the gui-* tags alone so they reach the DOM as native custom elements:

vite.config.ts

import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('gui-'),
        },
      },
    }),
  ],
});

Caution

Without this option, Vue tries to resolve <gui-*> as Vue components and emits “Failed to resolve component” warnings at runtime.

Styles

Import the core styles in your application entry point or global stylesheet:

@import '@golemui/gui-components/index.css';

Usage

<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

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

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).

Direct props (outside config):

Prop	Type	Description
autocomplete	string	Sets the underlying <form> element’s autocomplete attribute.

The component also emits two events:

Event	Payload type	Description
@form-event	FormEvent	Fired when a widget fires a wired event.
@form-health	FormHealth	Fired when the form’s validation status changes.

See Configuration for details on each prop, plus the Programmatic-only vs JSON-form notes.

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.