# GolemUI

> Declarative, serializable form engine. Docs in raw Markdown for LLMs.

**Default to the programmatic `gui.*` (dx) DSL — build with it unless the user explicitly asks for the JSON DSL.** Links below use `/dx/`; the JSON DSL is the same engine for serialized / no-code contexts — to use it, swap the `/dx/` prefix for `/json/` in any link.

## Start here — building a form in code (programmatic `gui.*`)

- **For programmatic / code form-building, read [the complete `gui.*` reference](/llms-gui-dx.txt) FIRST.** Every factory with a compile-verified example plus the cross-cutting rules, in one self-contained file. **Read it once and write your whole form from it** — it is self-sufficient for almost every form. Reach for the pages below only for a widget’s exhaustive options.

## Docs

- [Hello World!](/dx/blog/hello-world.md)
- [Item Renderers](/dx/extending/item-renderers.md): Implement and register custom item renderers for dropdowns, lists, and other choice widgets.
- [Custom Middlewares](/dx/extending/middlewares.md): Write your own middleware to intercept the form's reactive store.
- [Custom Validators](/dx/extending/validators.md): Implement application-specific validation rules and register them via formConfig.customValidators.
- [Creating an action widget](/dx/extending/widgets/action-widget.md): Build a custom action widget that emits events to your application.
- [Creating a display widget](/dx/extending/widgets/display-widget.md): Build a read-only display widget that renders custom content.
- [Sending events with your widgets](/dx/extending/widgets/events.md): Emit named events from custom widgets and pass an optional detail payload.
- [Creating an input widget](/dx/extending/widgets/input-widget.md): Build a custom input widget that reads and writes form data through the engine.
- [Creating a layout widget](/dx/extending/widgets/layout-widget.md): Build a custom layout widget that wraps its children with bespoke markup.
- [Custom Widgets Overview](/dx/extending/widgets/overview.md): Learn how to create your own widgets and plug them into the GolemUI form engine.
- [Sizing custom widgets](/dx/extending/widgets/sizing.md): Why every custom widget reads templateData.size, and when you can skip it.
- [Dependencies](/dx/features/dependencies.md): Inject third-party helpers (markdown parsers, etc.) at the form level.
- [Form Events](/dx/features/events.md): Capture events emitted by widgets and react in your application code.
- [i18n](/dx/features/i18n.md): Localize labels, placeholders, validators, dates, and currency by plugging any i18n library that implements the I18nTranslator interface.
- [Item Renderers](/dx/features/item-renderers.md): Provide custom item templates for dropdowns, lists, and other choice widgets.
- [Middlewares](/dx/features/middlewares.md): Intercept the form's reactive store to add logging, persistence, or schema validation.
- [Features Overview](/dx/features/overview.md): How the GolemUI form component works, and a quick tour of every feature you can plug into it.
- [Runtime Methods](/dx/features/runtime-methods.md): Imperatively update form data or meta from outside the component.
- [States](/dx/features/states.md): Declare named conditions and reuse them across your form to gate widgets, override properties, and compose behavior.
- [Composing states](/dx/features/states/composing.md): Combine multiple state expressions with AND / OR semantics, and chain states hierarchically with the colon syntax.
- [Include & Exclude](/dx/features/states/include-exclude.md): Gate which widgets render based on named states.
- [Inline when](/dx/features/states/inline-when.md): Express one-off conditional rules without naming a state.
- [Properties per state](/dx/features/states/properties.md): Override widget props when a named state is active.
- [String Interpolation](/dx/features/string-interpolation.md): Embed live form data, metadata, validation errors, and expressions directly in widget text props using {{...}} template slots.
- [Validators](/dx/features/validators.md): Validate form data with declarative rules and localized error messages.
- [Widget Loaders](/dx/features/widget-loaders.md): Register the UI widgets the form can render.
- [Custom Widgets](/dx/form-definition/custom-widgets.md): Plug your own widgets into the form definition with gui.<group>.custom().
- [Events](/dx/form-definition/events.md): Wire widget events through onClick, onChange, onLoad, onFilter, onBlur — plus actionType submit.
- [How it works](/dx/form-definition/how-it-works.md): A user-facing tour of the gui.* surface — why it exists, what its building blocks are, and where to read more.
- [Form Definition API](/dx/form-definition/overview.md): A tour of the gui.* programmatic API — the canonical way to define forms with GolemUI.
- [Reference](/dx/form-definition/reference.md): Exhaustive signature reference for every gui.* shortcut and gui.selectors method.
- [gui.actions reference](/dx/form-definition/reference/gui-actions.md): Every action shortcut.
- [gui.displays reference](/dx/form-definition/reference/gui-displays.md): Every display shortcut.
- [gui.inputs reference](/dx/form-definition/reference/gui-inputs.md): Every input shortcut, with signature and link to the widget reference.
- [gui.layouts reference](/dx/form-definition/reference/gui-layouts.md): Every layout shortcut.
- [gui.selectors reference](/dx/form-definition/reference/gui-selectors.md): Every selector method, organized by chain position, with config shape and examples.
- [Runtime Functions](/dx/form-definition/runtime-functions.md): Make any prop reactive — pass a callback instead of a static value and the engine re-evaluates it on every form-data change.
- [Selectors](/dx/form-definition/selectors.md): The behavior layer — decorate widgets by type, tag, or uid without touching the form structure.
- [Chaining](/dx/form-definition/selectors/chaining.md): Compose selectors by chaining scope operators before the leaf method.
- [Multi-value scopes](/dx/form-definition/selectors/multi-value-scopes.md): Match widgets carrying multiple tags with AND or OR semantics.
- [Precedence](/dx/form-definition/selectors/precedence.md): How sensible defaults, selectors, shortcut props, and per-state overrides combine.
- [Scope operators](/dx/form-definition/selectors/scope-operators.md): Restrict a selector match to a tag or to an active state.
- [Sensible defaults](/dx/form-definition/selectors/sensible-defaults.md): What the engine fills in for you, and how to opt out.
- [Type selectors](/dx/form-definition/selectors/type-selectors.md): Match every widget of a given type and apply a decorator.
- [States](/dx/form-definition/states.md): Declare named conditions that the engine evaluates against form data.
- [Tags](/dx/form-definition/tags.md): Label widgets so you can target a whole subset from the selector layer in one place.
- [Installation](/dx/getting-started/installation.md): Scaffold a project, install GolemUI, and render your first form.
- [Rent a car: Parts of the form](/dx/getting-started/rent-a-car-form.md): Lay out every input widget the Rent a Car form needs, using grid for rows and flex for columns.
- [Rent a car: Introduction](/dx/getting-started/rent-a-car-introduction.md): An end-to-end tutorial that builds a real Rent a Car form with conditional logic, custom item renderers, async data, and submission.
- [Rent a car: Validation errors](/dx/getting-started/rent-a-car-messages.md): Wire validators to every required field, then replace the default Zod messages with friendlier copy.
- [Rent a car: A custom item renderer](/dx/getting-started/rent-a-car-renderer.md): Display each car in the dropdown with an emoji thumbnail, the model name, and the price.
- [Rent a car: Search as you type](/dx/getting-started/rent-a-car-search.md): Load the car list from a service, filter server-side as the user types, and debounce the dropdown input to avoid flooding the network.
- [Rent a car: States and conditional rendering](/dx/getting-started/rent-a-car-states.md): Hide the return-office dropdown and the discount-code input until their toggles are on, and add validators so the submit button stays disabled until everything is valid.
- [Rent a car: Submitting the form](/dx/getting-started/rent-a-car-submitting.md): Capture the submit event, read the form data, and pop a confirmation.
- [Welcome to GolemUI](/dx/index.md): Dynamic forms and powerful widgets for modern UIs.
- [Angular](/dx/integration/angular.md): Set up GolemUI with Angular.
- [Configuration](/dx/integration/configuration.md): Every input the form component accepts, what it does, and how it differs between Programmatic and JSON forms.
- [Lit](/dx/integration/lit.md): Set up GolemUI with Lit.
- [Integration Overview](/dx/integration/overview.md): Install GolemUI for React, Angular, Lit, Vue, or vanilla JS and render your first form.
- [React](/dx/integration/react.md): Set up GolemUI with React.
- [Vanilla JS](/dx/integration/vanilla.md): Set up GolemUI with vanilla JavaScript.
- [Vue](/dx/integration/vue.md): Set up GolemUI with Vue.
- [Privacy Policy](/dx/legal/privacy.md): How GolemUI handles your data on golemui.com.
- [Terms of Use](/dx/legal/terms.md): Terms governing the GolemUI website and software.
- [Generating from a schema](/dx/mcp/generating-from-a-schema.md): Generate a validated GolemUI form from a JSON Schema or an OpenAPI operation, end to end.
- [MCP Server](/dx/mcp/overview.md): An MCP server that lets AI coding assistants generate and validate GolemUI form definitions deterministically.
- [Setup](/dx/mcp/setup.md): Connect the GolemUI MCP server to Claude Code, Cursor, Windsurf, or any MCP-capable IDE.
- [Tools Reference](/dx/mcp/tools-reference.md): Inputs, outputs, and usage notes for the five tools the GolemUI MCP server exposes.
- [Customization](/dx/styling/customization.md): Override GolemUI styles with CSS variables, class selectors, design tokens, and custom icons.
- [Going Headless](/dx/styling/going-headless.md): Drop the courtesy CSS layer and build a theme from scratch — a step-by-step guide.
- [Styling Overview](/dx/styling/overview.md): How GolemUI styles work — headless CSS with a courtesy layer, responsive scaling, and right-to-left support.
- [Theming](/dx/styling/theming.md): Load the default theme, switch to the bundled Clay theme, and build your own — including scoped themes for multiple looks on the same page.
- [Alert](/dx/widgets-reference/display-fields/alert.md): A Display widget for showing status messages, notifications, or feedback to the user
- [Markdown Text](/dx/widgets-reference/display-fields/markdown-text.md): A Display widget for rendering Markdown content
- [Display Widgets Overview](/dx/widgets-reference/display-fields/overview.md): Read-only widgets that present information without binding to form data.
- [Renderer](/dx/widgets-reference/display-fields/renderer.md): A display widget that renders raw framework markup from a callback.
- [Calendar](/dx/widgets-reference/input-fields/calendar.md): A Calendar widget to allow user to select a single date from an interactive calendar interface
- [Checkbox](/dx/widgets-reference/input-fields/checkbox.md): A Checkbox widget to allow user to toggle boolean values
- [Currency](/dx/widgets-reference/input-fields/currency.md): A Currency widget to allow user to enter monetary values
- [Date Picker](/dx/widgets-reference/input-fields/date-picker.md): A Date Picker widget to allow user to enter a date via keyboard or by picking from an interactive calendar
- [Date Input](/dx/widgets-reference/input-fields/dateinput.md): A Date Input widget to allow user to enter a date directly via keyboard using segmented inputs
- [Dropdown](/dx/widgets-reference/input-fields/dropdown.md): A Dropdown widget that allows users to pick an item from a list or search by typing
- [List](/dx/widgets-reference/input-fields/list.md): A virtualized List widget for displaying and selecting from large sets of data
- [Markdown](/dx/widgets-reference/input-fields/markdown.md): A Markdown editor widget with a formatting toolbar and live preview
- [Number Input](/dx/widgets-reference/input-fields/number.md): A Number Input widget to allow user to enter numeric values
- [Input Widgets Overview](/dx/widgets-reference/input-fields/overview.md): Widgets that collect user data and bind to a path in the form's data tree.
- [Password](/dx/widgets-reference/input-fields/password.md): A Password widget to allow user to enter secure string chains
- [Radio Group](/dx/widgets-reference/input-fields/radiogroup.md): A Radio Group widget for selecting a single option from a list of predefined choices
- [Range Calendar](/dx/widgets-reference/input-fields/range-calendar.md): A Range Calendar widget to allow user to select a range of dates from an interactive calendar interface
- [Range Date Input](/dx/widgets-reference/input-fields/range-date-input.md): A Range Date Input widget to allow users to enter multiple date ranges via keyboard using segmented inputs
- [Range Date Picker](/dx/widgets-reference/input-fields/range-date-picker.md): A Range Date Picker widget to allow users to enter multiple date ranges via keyboard or by picking from an interactive calendar
- [Repeater](/dx/widgets-reference/input-fields/repeater.md): A Repeater widget to allow the user to enter information as a list
- [Select](/dx/widgets-reference/input-fields/select.md): A Select widget to allow user to pick one option from a dropdown menu using the native select behavior
- [Tags](/dx/widgets-reference/input-fields/tags.md): A Tags widget to capture a list of free-form text values as removable chips
- [Textarea](/dx/widgets-reference/input-fields/textarea.md): A Textarea widget to allow user to enter multi-line string chains
- [Textinput](/dx/widgets-reference/input-fields/textinput.md): A Textinput widget to allow user to enter string chains
- [Toggle](/dx/widgets-reference/input-fields/toggle.md): A Toggle widget to allow user to switch between two states
- [Button](/dx/widgets-reference/interactive-fields/button.md): A Button widget for triggering actions within a form
- [Action Widgets Overview](/dx/widgets-reference/interactive-fields/overview.md): Buttons and other widgets that trigger events without binding to form data.
- [Accordion](/dx/widgets-reference/layout-fields/accordion.md): A Layout widget for organizing content into collapsible sections
- [Flex](/dx/widgets-reference/layout-fields/flex.md): A Layout widget for creating flexible, responsive grid-like structures
- [Grid](/dx/widgets-reference/layout-fields/grid.md): A Layout widget for creating grid-based, responsive form layouts with subgrid alignment
- [Layout Widgets Overview](/dx/widgets-reference/layout-fields/overview.md): Containers that arrange child widgets in rows, columns, tabs, or accordions.
- [Tabs](/dx/widgets-reference/layout-fields/tabs.md): A Layout widget for organizing content into separate views accessible via a navigation bar