golemui

The ultimate JSON form engine.

Get started · Documentation · How it works · Integrations

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

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:

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

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