@golemui/gui-components

Declarative, JSON-based forms for React, Angular, Lit, Vue, and vanilla JS.

                   

Get started · Documentation · How it works · Integrations

---

Overview

Underneath every form is a serializable JSON definition. Author it directly as schema-validated JSON, or with the typed gui builder API.

• 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 component styles once, anywhere in your app entry:

@import '@golemui/gui-components/index.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 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, calendar, repeater, list, custom
gui.actions	Buttons and custom actions	button, custom
gui.displays	Non-input content	display, alert, markdownText, custom
gui.layouts	Containers	flex, 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 formSubmit 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" @formSubmit="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.

Packages

Package	Description
@golemui/gui-react / -angular / -lit / -vue	Framework form component and bindings
@golemui/gui-shared	The gui builder and form definition types (GuiFormInitConfig)
@golemui/gui-components	Default widget components and the stylesheet (index.css)
@golemui/core	Framework-agnostic form runtime and shared types (FormEvent, ValidateOn)
@golemui/gui-validators	Validation schemas (@standard-schema/spec)
@golemui/gui-schemas	JSON Schemas for form definitions
@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.

Contributing

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

License

MIT