Skip to content
Forms, switch product

Lit

Terminal window
npm i @golemui/core @golemui/gui-shared @golemui/lit @golemui/gui-lit @golemui/gui-components --save

Import the core styles in your HTML or application entry point:

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

<gui-form> only needs a formDef. The framework’s built-in widget set is loaded automatically, and an empty form renders fine without initial data.

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { gui } from '@golemui/gui-shared';
import '@golemui/gui-lit';
@customElement('my-form')
export class MyForm extends LitElement {
config = {
formDef: [gui.inputs.textInput('username', { label: 'Username' })],
};
override createRenderRoot() {
return this;
}
render() {
return html`<gui-form .config=${this.config}></gui-form>`;
}
}
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@golemui/gui-lit';
import formDef from './my-form.json';
@customElement('my-form')
export class MyForm extends LitElement {
config = { formDef };
override createRenderRoot() {
return this;
}
render() {
return html`<gui-form .config=${this.config}></gui-form>`;
}
}

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.

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { gui } from '@golemui/gui-shared';
import '@golemui/gui-lit';
import { myCustomWidgets } from './my-custom-widgets';
@customElement('my-form')
export class MyForm extends LitElement {
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
};
override createRenderRoot() {
return this;
}
render() {
return html`<gui-form .config=${this.config}></gui-form>`;
}
}
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@golemui/gui-lit';
import { myCustomWidgets } from './my-custom-widgets';
import formDef from './my-form.json';
@customElement('my-form')
export class MyForm extends LitElement {
config = {
formDef,
data: { username: 'octocat' }, // optional — initial form data
customWidgetLoaders: myCustomWidgets, // optional — only when the form references widgets you've built yourself
};
override createRenderRoot() {
return this;
}
render() {
return html`<gui-form .config=${this.config}></gui-form>`;
}
}

All initialization properties are bundled in the required .config property (GuiFormInitConfig):

config propertyTypeDescription
formDef (required)FormInputProgrammatic gui.* array or parsed JSON form definition.
formSelectorsGslSelectorsInputGSL selector decorators. Programmatic-only.
formConfigDxFormConfigDX engine wiring (loaders, item renderers, dependencies, validateOn, …). Programmatic-only.
dataRecord<string, any>Initial form data.
metaRecord<string, any>Out-of-band metadata you want to thread through events and state.
customWidgetLoadersWidgetLoaders<Type<WithWidget>>Custom widget map; merged with the default Lit widget set.
itemRenderersRecord<string, LitItemRenderer<any>>Custom item-renderer map (for dropdown, list, etc.).
customValidatorsCustomValidatorSchemasCustom validator schemas referenced by validator: { type: 'custom', ... }.
middlewaresMiddleware<State, Action>[]Store middlewares (logging, persistence, devtools).
validateOnValidateOnWhen validation runs: 'eager' (default), 'change', 'blur', 'submit', or an array.
dependenciesDependenciesExternal helpers (e.g. a markdown parser).
localizationI18nTranslatorTranslator implementing the I18nTranslator interface.
formNamestringForm identifier (useful when you have several forms on a page). Required by @golemui/lit/ssr: the server and the client must produce the same ids.
expressionPolicy'warn' | 'strict'How strictly the form treats its expressions. Defaults to 'warn'. See Configuration.

Direct properties (outside config):

PropertyTypeDescription
.autocompletestringSets the underlying <form> element’s autocomplete attribute.
.formHealthBoundaryFormHealthBoundaryFunction that wraps the form and renders the error UI for an errored FormHealth. Defaults to a red banner. Set as a property (not an attribute). See Configuration.

The element also dispatches three custom events:

EventDetail typeDescription
@formEventFormEventFired when a widget fires a wired event.
@formSubmitFormSubmitEventFired when a submit button is clicked and the whole form passes validation.
@formHealthFormHealthFired 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 property, plus the Programmatic-only vs JSON-form notes.

Build your own widgets by extending LitElement, consuming the form context with @consume({ context: formContext }), and providing the appropriate adapter (@provide({ context: inputContext }) and friends — all named imports from @golemui/lit). Because Lit widgets are native web components, they also work inside React or Angular hosts when paired with a thin shim. See Extending GolemUI / Widgets for the full walkthrough.

Lit renders the whole form on the server: renderTemplate from @golemui/lit/ssr emits the widget internals and values, and resumeServerRenderedForm takes over in the browser. Preload the widgets on both sides and set formName. See Lit SSR for the contract and the server API, and Astro for the page-level wiring.