Lit

Installation

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

Styles

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

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

Usage

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

Programmatic

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>`;
  }
}

JSON

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

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.

Programmatic

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>`;
  }
}

JSON

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

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.

Direct properties (outside config):

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

The element also dispatches two custom events:

Event	Detail type	Description
@formEvent	FormEvent	Fired when a widget fires a wired event.
@formHealth	FormHealth	Fired when the form’s validation status changes.

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

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.