Lit
Installation
Section titled “Installation”npm i @golemui/core @golemui/gui-shared @golemui/lit @golemui/gui-lit @golemui/gui-components --saveStyles
Section titled “Styles”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>`; }}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.
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>`; }}<gui-form> properties
Section titled “<gui-form> properties”All initialization properties are bundled in the required .config property (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<Type<WithWidget>> | Custom widget map; merged with the default Lit widget set. |
itemRenderers | Record<string, LitItemRenderer<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 | Form 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):
| Property | Type | Description |
|---|---|---|
.autocomplete | string | Sets the underlying <form> element’s autocomplete attribute. |
.formHealthBoundary | FormHealthBoundary | Function 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:
| Event | Detail type | Description |
|---|---|---|
@formEvent | FormEvent | Fired when a widget fires a wired event. |
@formSubmit | FormSubmitEvent | Fired when a submit button is clicked and the whole form passes validation. |
@formHealth | 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 property, plus the Programmatic-only vs JSON-form notes.
Custom widgets in Lit
Section titled “Custom widgets in Lit”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.
Server-side rendering
Section titled “Server-side rendering”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.