Forms, switch product
announcements

GolemUI v2.1.2: one set of ids per form, and a lighter form validator

GolemUI v2.1.2 is released. It is a patch release after v2.1.1 with two changes: forms on the same page stop sharing DOM ids, and the form validator in @golemui/gui-mcp gets much smaller and faster. Most apps need no change. If your CSS or your tests select GolemUI fields by id, read Upgrading first.

In 2.1.1, a widget built its DOM ids from its uid alone. A login form and a newsletter form on the same page, each with an email field, both rendered an input with id="email-textinput". The browser resolves an id to the first element that has it, so the label, hint and error of the second form pointed at the input of the first one. A click on the second label focused the wrong field, and a screen reader read the wrong hint.

Now every DOM id inside a form starts with the form’s formName: the control, its label, hint and errors, the popups, the list options, the tab and accordion parts, and the widget’s host element. The two forms below both have an email field. Click the Email label of the second one, and the cursor goes to the newsletter field:

Give each form a name to know its ids:

<GuiForm config={{ formDef: login, formName: 'login' }} />
<GuiForm config={{ formDef: newsletter, formName: 'newsletter' }} />

The inputs get the ids login-email-textinput and newsletter-email-textinput. A form without a formName generates one, so its ids are scoped too, but you can’t predict them. Set a name when the server renders the form, and when your CSS or tests select GolemUI elements by id. See formName.

Only DOM ids take the prefix. The widget uid stays as it is, and so do the store, the form events, the after references and the data-cy attributes. Tests that select by data-cy keep working.

Every element of GolemUI Components has a new id-prefix attribute (the idPrefix property). GolemUI Forms sets it to the form’s formName. An element used on its own takes no prefix, so its ids don’t change. Use it when two elements on one page share a uid:

<gui-textinput uid="email" id-prefix="billing" label="Email"></gui-textinput>
<gui-textinput uid="email" id-prefix="shipping" label="Email"></gui-textinput>

The label, hint, errors and every ARIA reference of each element follow its own prefix.

The hooks, composables and adapters now give your custom widgets two more values: domId, the widget uid behind the form’s name, and formName. Use domId for the ids your widget renders, and pass formName as idPrefix to the GolemUI Components elements inside it:

const { domId, value, onValueChanged } = useInputWidget<number, RatingProps>(
widget,
);
return (
<div className="rating" id={domId}>
{/* … */}
</div>
);

In Angular and Lit, read adapter.domId and adapter.formName. See DOM ids.

@golemui/gui-mcp checks form definitions: the json_validate_form_definition tool, the validate-json command and validateFormDefinition in your own code. In 2.1.1 its validator was one module of 4.73 MB minified. Now each widget type has its own module.

WhatMinifiedGzipped
2.1.1: the validator module4.73 MB362 KB
2.1.2: validateFormDefinition2.38 MB171 KB
2.1.2: lazy entry, everything a typical form loads305 KB48.5 KB
  • A lazy entry for browsers. @golemui/gui-mcp/json/lazy has validateFormDefinitionAsync, which loads only the validators of the widget types the form uses and returns the same result as validateFormDefinition. The typical form in the table has six widgets. preload() starts loading the common validators before the first form arrives.
  • Much faster. The old validator took time exponential in the depth of the layouts. A 4KB issue tracker form took 1.1s to validate. The test suite’s 5,099 forms now validate in 108ms instead of 39s.
  • Clearer errors. A layout with an empty children array gets a minItems error instead of a generic one. A repeater template that is not a built-in layout, such as a chunk reference, a custom widget or an input, gets a position error that says so.
import {
preload,
validateFormDefinitionAsync,
} from '@golemui/gui-mcp/json/lazy';
preload(['textinput', 'select']);
const result = await validateFormDefinitionAsync({ formDefinition: myForm });
if (!result.valid) console.error(result.errors);

@golemui/gui-mcp/json stays synchronous and bundles anywhere, Cloudflare Workers included. Neither entry compiles code at runtime, so both work under a strict Content Security Policy. See the gui-mcp README.

  • Upgrade every @golemui/* package to 2.1.2 at once.
  • Selectors by id: CSS, tests or scripts that select a Forms widget by id, such as #email-textinput, no longer match. Set a formName and add it to the selector (#signup-email-textinput), or select by data-cy or by class.
  • Your own ARIA references: an aria-describedby, aria-controls or <label for> outside the form that points at a GolemUI id needs the prefix too.
  • Custom widgets: a widget that renders id={uid} still works, but two forms that use it share that id. Switch to domId.
  • gui-mcp: nothing to change. To validate forms in a browser, switch to @golemui/gui-mcp/json/lazy.

The full list of changes is in the changelog.

Previous GolemUI v2.1.1: validation and repeater fixes, and a deprecation schedule Next GolemUI v2.2.0: checkbox groups, ratings, badges, progress bars and spinners