golemui

---

Overview

Define forms with the typed gui builder API, or as schema-validated JSON. Both produce the same serializable definition.

• One definition renders in React, Angular, Lit, Vue, or vanilla JS.
• Validation, conditional fields, i18n, and accessibility come from the schema and runtime.
• The output is plain data: store it, transfer it, diff it, generate it.

Installation

Install the four @golemui/* packages for your framework. The versions are published together; use matching versions.

# React
npm i @golemui/core @golemui/react @golemui/gui-react @golemui/gui-shared

# Angular
npm i @golemui/core @golemui/angular @golemui/gui-angular @golemui/gui-shared

# Lit
npm i @golemui/core @golemui/lit @golemui/gui-lit @golemui/gui-shared

# Vue
npm i @golemui/core @golemui/vue @golemui/gui-vue @golemui/gui-shared

# Vanilla JS (web component)
npm i @golemui/core @golemui/lit @golemui/gui-lit @golemui/gui-shared

Import the two stylesheets once, in this order, anywhere in your app entry:

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

Full walkthrough at golemui.com/getting-started/installation.

Quick start

Define a form as an array of gui builders and pass it to the framework component (React shown):

import '@golemui/gui-components/index.css';
import '@golemui/gui-shared/forms.css';
import type { FormSubmitEvent } from '@golemui/core';
import { GuiForm } from '@golemui/gui-react';
import { gui } from '@golemui/gui-shared';

const formDef = [
  gui.inputs.textInput('email', {
    label: 'Email',
    validator: { type: 'string', required: true, format: 'email' },
  }),
  gui.inputs.password('password', {
    label: 'Password',
    validator: { type: 'string', required: true, minLength: 8 },
  }),
  gui.inputs.checkbox('newsletter', {
    label: 'Subscribe to the newsletter',
    include: { when: '!!$form.email' },
  }),
  gui.actions.button({
    label: 'Sign up',
    actionType: 'submit',
    disabled: { when: '$formIsInvalid' },
  }),
];

function handleSubmit(event: FormSubmitEvent) {
  console.log(event.data);
}

export function App() {
  return <GuiForm config={{ formDef }} formSubmit={handleSubmit} />;
}

The submit button stays disabled while the form is invalid ($formIsInvalid is a built-in validity flag); on submit, formSubmit receives the collected data.

The same formDef value renders in every supported framework. See Integrations for per-framework setup, and the starter templates under templates/ for runnable examples.

Core concepts

Form definition. A form is an array of nodes (or a single node). Each node is either a gui builder result or a render function. The output is serializable JSON, so a definition can be stored, transferred, and rendered later.

The gui builder. Exported from @golemui/gui-shared, grouped into namespaces:

Namespace	Purpose	Examples
gui.inputs	Field widgets	textInput, numberInput, password, textarea, checkbox, dropdown, select, radiogroup, currency, tags, datePicker, timeInput, dateTimeInput, calendar, repeater, list, custom
gui.actions	Buttons and custom actions	button, custom
gui.displays	Non-input content	display, alert, markdownText, custom
gui.layouts	Containers	grid, tabs, accordion, custom
gui.selectors	Select and update widgets by type, uid, tag, or state	-

Conditional fields. Widgets accept include / exclude with a reactive expression over form data:

gui.inputs.radiogroup('city', { label: 'City', include: { when: '!!$form.country' } });
gui.actions.button({ label: 'Reset', include: { when: '$form.debug === true' } });

$form.<path> reads the current form data; the expression is evaluated at runtime.

Rendering per framework. Every adapter takes the definition through a config prop and emits a form submit event:

Framework	Import	Element
React	import { GuiForm } from '@golemui/gui-react'	<GuiForm config={config} formSubmit={handler} />
Vue	import { GuiForm } from '@golemui/gui-vue'	<GuiForm :config="config" @form-submit="handler" />
Angular	import { FormComponent } from '@golemui/gui-angular'	<gui-form [config]="config" (formSubmit)="handler($event)">
Lit	import '@golemui/gui-lit'	<gui-form .config=${config} @formSubmit=${handler}>

For vanilla JS, import @golemui/gui-lit to register the <gui-form> custom element, then set el.config = config and listen for the formSubmit event (e.detail is the FormSubmitEvent).

Features

• Validation. @standard-schema/spec compliant. Built-in string, number, boolean, array, and custom validators with rules such as required, minLength, format, minimum/maximum, and const. Error messages are localizable, and timing is configurable via validateOn (change, blur, submit, eager). Docs
• Internationalization. Provide an I18nTranslator adapter (i18next, Lingui, or your own) through localization. Labels, hints, and validator messages are translatable, with live language switching and automatic RTL. Docs
• Accessibility. Native form elements with ARIA wiring managed for you: aria-describedby for hints, aria-invalid and aria-errormessage on errors, plus keyboard navigation on interactive widgets.
• Theming. Styling is driven by CSS custom properties (design tokens) from a single stylesheet. Override tokens, or supply your own widget components through customWidgetLoaders. Docs
• AI assistants (MCP). @golemui/gui-mcp ships a golemui-mcp Model Context Protocol server with tools to validate form definitions, generate them from JSON Schema or OpenAPI, and type-check gui.* code.
• AI assistants (skill). An installable agent skill grounds coding agents in the real GolemUI API even without the MCP connected - npx skills add golemui/golemui (works with Claude Code, Cursor, and other skills.sh-compatible agents). Its API reference is generated from the same compile-verified registry the MCP serves, so the two never disagree.

Packages

Package	Description
@golemui/gui-react / -angular / -lit / -vue	Framework form component and bindings
@golemui/gui-shared	The gui builder, form definition types (GuiFormInitConfig) and forms.css
@golemui/gui-components	Lit web components, usable with or without forms, and their stylesheets
@golemui/core	Framework-agnostic form runtime and shared types (FormEvent, ValidateOn)
@golemui/gui-validators	Validation schemas (@standard-schema/spec)
@golemui/schemas	The shared core JSON Schema (common defs) and the schema tree generator
@golemui/gui-schemas	JSON Schemas for gui form definitions, generated from the widget manifest
@golemui/gui-mcp	MCP server for coding assistants

Import only from a package's public entry points. The @golemui/*/internals paths are internal and unstable.

Documentation

golemui.com for full docs, API reference, per-framework guides, examples, and migration paths.

Upgrading from 1.x? See MIGRATION-v2.md.

Contributing

See CONTRIBUTING.md. The repository is an Nx monorepo; tests run on Vitest, and pull requests follow Conventional Commits.

License

MIT