Validators

Validators provide contextual messages for errors in input widgets. Each validator validates a particular shape of data — string, number, boolean, array — and supports a set of rules tailored to that shape. You can also create custom validators for application-specific rules.

Adding validators to your inputs

Add a validator property to any input widget. The example below requires a non-empty password:

import { gui } from '@golemui/gui-shared';

gui.inputs.textInput('user.password', {
  validator: {
    type: 'string',
    required: true,
  },
});

Validators stack — combine multiple rules and you’ll see one message per failing rule. The next example checks the password is between 8 and 20 characters long, and that it contains both letters and numbers:

import { gui } from '@golemui/gui-shared';

gui.inputs.textInput('user.password', {
  validator: {
    type: 'string',
    required: true,
    minLength: 8,
    maxLength: 20,
    pattern: '^(?=.*[A-Za-z])(?=.*\\d)[A-Za-z\\d]+$',
  },
});

Custom error messages

By default, validators use Zod’s built-in messages. Override them by providing a messages property — a record where each key corresponds to a validation rule and the value is either a plain string or a translation config for i18n.

Plain string messages

gui.inputs.textInput('user.password', {
  validator: {
    type: 'string',
    required: true,
    minLength: 8,
    messages: {
      required: 'Please enter your password',
      minLength: 'Password must be at least 8 characters',
    },
  },
});

Translation config messages (i18n)

gui.inputs.textInput('user.password', {
  validator: {
    type: 'string',
    required: true,
    messages: {
      required: {
        key: 'errors.password.required',
        default: 'Please enter your password',
      },
    },
  },
});

A more complete example combining several rule types:

Validator types reference

Each validator type supports a specific set of rules and message keys.

String validator

Property	Message key	Description
(type check)	`invalid`	Value is not a string
`required`	`required`	Empty string when `required: true`
`minLength`	`minLength`	String length is below the minimum
`maxLength`	`maxLength`	String length exceeds the maximum
`pattern`	`pattern`	String does not match the regex pattern
`format`	`format`	String does not match the format (`email`, `url`, `uuid`, `hostname`, `ipv4`, `ipv6`, `date`, `time`, `date-time`, `duration`)
`enum`	`enum`	Value is not one of the allowed values
`const`	`const`	Value does not match the exact value

Number validator

Property	Message key	Description
(type check)	`invalid`	Value is not a number
`required`	`required`	Empty string when `required: true`
`minimum`	`minimum`	Value is below the minimum
`maximum`	`maximum`	Value exceeds the maximum
`exclusiveMinimum`	`exclusiveMinimum`	Value is not greater than the exclusive minimum
`exclusiveMaximum`	`exclusiveMaximum`	Value is not less than the exclusive maximum
`multipleOf`	`multipleOf`	Value is not a multiple of the specified number
`enum`	`enum`	Value is not one of the allowed values
`const`	`const`	Value does not match the exact value

Boolean validator

Property	Message key	Description
(type check)	`invalid`	Value is not a boolean
`required`	`required`	Empty string when `required: true`
`const`	`const`	Value does not match the expected boolean value

Array validator

Property	Message key	Description
(type check)	`invalid`	Value is not an array
`required`	`required`	Array is empty when `required: true`
`minItems`	`minItems`	Array has fewer items than the minimum
`maxItems`	`maxItems`	Array has more items than the maximum

Configuring when validation triggers

The validateOn property in formConfig controls when field validation runs.

type ValidateOn =
  | 'eager'
  | 'change'
  | 'blur'
  | 'submit'
  | ('change' | 'blur' | 'submit')[];

When not set, the default validateOn behaviour is 'eager'.

Mode	Triggers when
`'change'`	The user changes the field value
`'blur'`	The user leaves the field
`'submit'`	A `submit` event is emitted (all fields are touched first)
`'eager'`	Any of the above happens (default)

gui.actions.submitButton({ label: 'Create User' });

const formConfig = { validateOn: 'change' };

export function FormPage() {
  return (
    <div>
      <React.FormComponent
        (...)
        formConfig={formConfig}
      />
    </div>
  );
}

import * as Core from '@golemui/core';

@Component({
  selector: 'my-form-app',
  template: `<gui-form
    (...)
    [formConfig]="formConfig">
    </gui-form>
  `,
})
class MyFormApp {
  protected formConfig = {
    validateOn: 'change' as Core.ValidateOn,
  };
}

import * as Core from '@golemui/core';

@customElement('lit-form')
export class FormElement extends LitElement {
  protected formConfig = {
    validateOn: 'change' as Core.ValidateOn,
  };

  render() {
    return html`
      <gui-form
        (...)
        .formConfig=${this.formConfig}
      ></gui-form>
    `;
  }
}