Docs

Main site

Installation Browser support Extend config MCP server
Validation Page speed testing Responsive design
Accordion Aspect Ratio Avatar Badge Banner Bento Grid Blockquote Breadcrumbs Button Callout Card Drawer Dropdown Link Modal Navbar Navblock Pagination Popover Progress Separator Tabs Timeline Toast Tooltip
Checkbox Datepicker File upload Form field Input Label OTP Radio Range Select Textarea Toggle
Header Footer
Accordion Auth Checkbox & Radio Content Drawers Features Modals Statistics & Metrics Teams
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Concepts Validation

Validation

Every form component shares the same built-in validation surface — three properties, two slots, one event and two methods — so you can validate any form with your own rules and no extra library.

Introduction

The design system does not ship a validation engine. It ships a surface: a uniform way to say "this field is invalid, here is why", and a uniform way to be told "the user did something, here is the current value and its validity". Whether a value is acceptable is your business logic — a regex, a server call, a schema library, or the browser's own constraint validation.

Twelve controls implement the full surface: aegov-input, aegov-textarea, aegov-select, aegov-checkbox, aegov-checkbox-group, aegov-radio, aegov-radio-group, aegov-toggle, aegov-range, aegov-otp, aegov-fileupload and aegov-datepicker. The aegov-form-field wrapper carries the three properties and cascades them to the control inside it.

<aegov-input id="email" name="email" type="email" hint="We will send confirmation here"></aegov-input>

<script type="module">
  const input = document.querySelector('#email');

  input.addEventListener('aegovValidate', (e) => {
    if (e.detail.trigger !== 'blur') return;
    const ok = /\S+@\S+\.\S+/.test(e.detail.value);
    input.isInvalid = !ok;
    input.errorMessage = ok ? '' : 'Enter a valid email address';
  });
</script>

The two fields below show the states that listener produces: the hint before an error, and the error after an invalid email address.

Email address Alternative email address

That is the whole contract: no framework, no library, no schema. For ready-made patterns — reusable rules, whole forms, cross-field and server-side checks — see Bring your own validator.

Properties

Property Attribute Description Type Default
isInvalid is-invalid Toggles the visual invalid state. Sets aria-invalid="true" on the inner control and adds the is-invalid class to the host element. boolean false
errorMessage error-message Error text shown below the control while is-invalid is true. The error slot takes precedence when it has content. string ''
hint hint Helper text shown below the control whenever no error is showing. The hint slot takes precedence when it has content. string '' (undefined on aegov-checkbox, aegov-radio, aegov-toggle and aegov-fileupload)

Error and hint are mutually exclusive: while the component is invalid the error replaces the hint, and the hint comes back when the error is cleared. You do not need to hide the hint yourself.

Slots

Slot Description
error Custom error markup — icons, links, multi-line content. Shown only while is-invalid is true.
hint Custom hint markup. Shown only when no error is showing.
<aegov-input field-id="username" name="username" is-invalid>
  <span slot="error">
    That username is taken. <a href="/help/usernames">Choose another</a>.
  </span>
</aegov-input>
Username That username is taken. Choose another.

When the error slot has content, error-message is ignored. The same applies to hint and the hint slot.

The aegovValidate event

Fired on every interaction trigger, and by validate(). This is how you learn that something happened and what the current value and validity are. The event bubbles, so one listener on a <form> hears every field inside it.

event.detail: {
  name: string | null;               // from the `name` attribute, null if unnamed
  value: T;                          // typed per component — see Value types below
  validity: AegovValidityState;      // native ValidityState shape
  validationMessage: string;         // message for the current state, '' when valid
  customError: string | null;        // the message set via setCustomValidity() or errorMessage, else null
  trigger: 'input' | 'change' | 'blur' | 'submit' | 'manual';
}

Triggers

Trigger Fired when
input The value changes while typing, keystroke by keystroke.
change The value is committed — a selection made, a checkbox toggled, a file chosen, every cell of an OTP code filled.
blur The control loses focus. This is when most validation should run.
submit You called validate('submit') as part of a submit.
manual You called validate() without a trigger.

Values you set from code fire no aegovValidate, just as a native input fires no events for them. Call validate() when you need a verdict on such a value. As with native inputs, minlength and maxlength on aegov-input and aegov-textarea are checked only on what the user typed, so validate() reports a value set from code as valid however long it is.

Gate on the trigger rather than validating on every event. Validating while someone is still typing their email address tells them they are wrong before they have finished:

input.addEventListener('aegovValidate', (e) => {
  if (e.detail.trigger === 'input') return;   // let them finish
  applyMyRules(e.detail);
});

Validity flags

detail.validity has the same shape as the browser's ValidityState. Components built on a native control report the browser's own flags; the others set the same flags themselves, so the shape is identical either way.

Flag Meaning
valueMissing is-required and empty — on a group, nothing chosen.
typeMismatch Wrong shape for the declared type (an email without @). On aegov-fileupload, a file whose type is not in accept.
patternMismatch Does not match pattern — on aegov-input or aegov-otp.
tooShort / tooLong Outside minlength / maxlength. aegov-otp reports tooShort until every cell is filled; aegov-fileupload reports tooLong for a file over max-file-size; a datepicker range outside min-range / max-range reports these too.
rangeUnderflow / rangeOverflow Before min / after max — number inputs and datepicker.
stepMismatch Not on a valid step increment.
badInput The browser cannot turn what was typed into a value.
customError A message was set with setCustomValidity(). aegov-fileupload also uses it when more than max-files files are chosen, and aegov-datepicker when its value falls on a blackout date — with its own message, in English or Arabic like the rest of its text.
valid true only when every other flag is false.

On aegov-fileupload, a rejected file (wrong type, too large, too many files) keeps its flag for as long as its message is shown — until the next selection, a removal, clear() or a form reset.

Methods

Method Returns Description
validate(trigger?) Promise<{ valid, message, validity }> Checks the field now and fires aegovValidate. trigger defaults to 'manual'. It reports problems; it does not show them — set isInvalid and errorMessage (or use a listener) to display them.
setCustomValidity(message) Promise<void> Mirrors the native method. A non-empty message marks the field invalid, shows the message, sets validity.customError and blocks form submission — except on aegov-checkbox-group and aegov-radio-group, where only validate() reports it. An empty string clears all of that.
const result = await input.validate('submit');
// result: { valid: boolean, message: string, validity: AegovValidityState }

if (!result.valid) input.focus();

setCustomValidity() is the right tool for errors that come from outside the browser — a server rejection, a cross-field rule, a business constraint. The error stays until you clear it or the form is reset, even when the field is validated again:

const res = await api.checkEmiratesId(value);
await field.setCustomValidity(res.ok ? '' : res.reason);

isInvalid + errorMessage, by contrast, only change what is displayed: validate() and the form still go by the field's own constraints.

Form integration

Ten of the form controls are form-associated: aegov-input, aegov-textarea, aegov-select (in both appearances), aegov-checkbox, aegov-radio, aegov-toggle, aegov-range, aegov-otp, aegov-fileupload and aegov-datepicker. Inside a <form> they behave like native controls: they are included in new FormData(form) (an empty text-like field as an empty string; an empty file upload, multiple select or datepicker range adds no entry), take part in form.checkValidity() and form.reportValidity(), and match :invalid. form.reset() restores the value each one started with and clears the error state — a custom error, errorMessage and isInvalid. Values you set from code are submitted too.

A control with is-disabled leaves the form like a disabled native control: it is not in FormData, does not block form.checkValidity(), and its validate() reports it valid. A disabled <fieldset> does the same for the form-associated controls inside it, but a checkbox or radio group's own validate() still checks it there.

aegov-checkbox-group and aegov-radio-group are aggregators: each child checkbox or radio submits its own value, and the group holds no value of its own. A group's is-required therefore does not block form.checkValidity() — check groups with their own validate(), as the submit pattern below does.

Standalone aegov-radio elements never form a group, even when they share a name: each one can be checked on its own. Wrap related radios in aegov-radio-group.

Form association relies on ElementInternals, which is why Safari 16.4 is the minimum version — see Browser support.

Value types

detail.value and what the form submits differ per component:

Component detail.value Submitted in FormData
aegov-input, aegov-textarea, aegov-otp string the string, empty when nothing was entered
aegov-checkbox, aegov-toggle boolean (checked) 'on' — or its value — when checked; nothing when not
aegov-radio boolean (checked) its value when checked ('on' without one)
aegov-select string the selected value
aegov-select with is-multiple string[] one entry per selected value, all under name
aegov-range number the number as a string
aegov-range with mode="range" { low, high } name-low and name-high
aegov-datepicker string (YYYY-MM-DD) the date string
aegov-datepicker with appearance="range" { start, end } name-start and name-end
aegov-fileupload File[] one entry per file, all under name
aegov-checkbox-group string[] of checked values each child submits individually
aegov-radio-group string or undefined the selected child's name=value

To set values from code, use the property: a comma-separated string for a multiple select ('a,c'), valueLow and valueHigh for a range in range mode, and '2026-09-01/2026-09-05' for a datepicker range.

const data = new FormData(document.querySelector('#application'));

data.get('emiratesId');         // '784-1990-1234567-1'
data.getAll('documents');       // [File, File]
data.get('appointment-start');  // '2026-09-01'

Accessibility built in

The components handle the ARIA wiring; you do not need to add any of this yourself:

  • aria-invalid is set on the inner control whenever is-invalid is true, and removed when it is not.
  • aria-describedby points at the hint and error. The component wires its own hint and error IDs to the inner control, alongside any IDs you set in aria-describedby on the component. Your IDs are looked up inside the component, though — IDs do not cross the shadow boundary — so they cannot reach text elsewhere on the page. Put extra help text in the hint slot.
  • Errors are announced at the right moment. The error region gets role="alert" only once the user has left the field for the first time, or as soon as a submit finds the field invalid — validate('submit'), form.checkValidity(), form.reportValidity() or a native submit (on checkbox and radio groups, only validate('submit')). Without that gate a screen reader would announce a half-finished error on every keystroke.
  • The is-invalid class is added to the host element, so you can style invalid state without watching the property.

Your responsibilities

  • Write messages that say what to do, not what went wrong: "Enter a date in the future" beats "Invalid date".
  • Do not rely on colour alone (WCAG 2.2 SC 1.4.1). The error text is the accessible signal; the red border is decoration. Always set error-message (or fill the error slot) when you set is-invalid.
  • Move focus to the first invalid field on a failed submit. The components do not move focus for you.
  • Give every control a name if you read the form with FormData, and a label: aegov-label inside an aegov-form-field, or the component's own label property on checkbox, radio, toggle, range, file upload and the two groups.
  • Summarise form-level failures separately. A field announces its own error; "3 problems with your application" belongs in an error summary at the top of the form — see the recipe in Bring your own validator.

The aegov-form-field cascade

aegov-form-field can carry is-invalid, error-message and hint for the control it wraps. The values pass down to the first form control inside it — but only where that control has not set its own value. The control's own value always wins. Changing a value on the wrapper updates it on the control, and clearing it there clears what the wrapper set.

<aegov-form-field is-invalid error-message="Enter your Emirates ID to continue">
  <aegov-label>Emirates ID</aegov-label>
  <aegov-input name="emiratesId"></aegov-input>
</aegov-form-field>
Emirates ID

The wrapper also adds is-invalid to its own .aegov-form-field element, so label and control can be styled together. Use the cascade when the wrapper is the natural owner of the message — for example, when your form code tracks state per field rather than per component.

Whole-form validation on submit

The pattern that covers most services: check every control on submit, show each error under its field, stop the submission if anything fails, and move focus to the first problem.

<form id="application" novalidate>
  <aegov-input name="fullName" is-required></aegov-input>
  <aegov-input name="email" type="email" is-required></aegov-input>
  <aegov-datepicker name="appointment" is-required></aegov-datepicker>
  <aegov-button type="submit" variant="primary">Submit</aegov-button>
</form>

<script type="module">
  const form = document.querySelector('#application');

  const CONTROLS =
    'aegov-input, aegov-textarea, aegov-select, aegov-checkbox, aegov-checkbox-group, ' +
    'aegov-radio, aegov-radio-group, aegov-toggle, aegov-range, aegov-otp, aegov-fileupload, aegov-datepicker';

  // Your own copy for each kind of problem (the same helper as in Bring your own validator).
  function messageFor(el, detail) {
    const v = detail.validity;
    if (v.valid)           return '';
    if (v.customError)     return detail.validationMessage;   // set with setCustomValidity()
    if (v.valueMissing)    return 'This field is required';
    if (v.typeMismatch)    return el.localName === 'aegov-fileupload' ? 'Choose an allowed file type'
                             : el.type === 'url' ? 'Enter a valid web address' : 'Enter a valid email address';
    if (v.tooShort)        return 'Too short';
    if (v.tooLong)         return el.localName === 'aegov-fileupload' ? 'Choose a smaller file' : 'Too long';
    if (v.rangeUnderflow)  return 'Choose a later date';
    if (v.rangeOverflow)   return 'Choose an earlier date';
    if (v.patternMismatch) return 'Use the required format';
    return 'Check this field';
  }

  // Show (or clear) each field's error whenever it is validated.
  form.addEventListener('aegovValidate', (e) => {
    if (e.detail.trigger === 'input') return;
    e.target.isInvalid = !e.detail.validity.valid;
    e.target.errorMessage = messageFor(e.target, e.detail);
  });

  form.addEventListener('submit', async (e) => {
    e.preventDefault();

    const controls = [...form.querySelectorAll(CONTROLS)];
    const results = await Promise.all(controls.map((c) => c.validate('submit')));
    const firstBad = controls.find((_, i) => !results[i].valid);

    if (firstBad) {
      // A checkbox or radio group takes focus on its first option.
      (firstBad.querySelector('aegov-checkbox, aegov-radio') ?? firstBad).focus();
      return;
    }

    await api.submitApplication(new FormData(form));   // your own submit function
  });
</script>
  • novalidate on the form turns off the browser's own error bubbles, so your messages under the fields are the only ones shown. The checks themselves still run.
  • validate() reports; the listener displays. Without the aegovValidate listener the submit would stop and move focus, but no field would show its error.
  • Fields with their own rules: write those rules with setCustomValidity(). The shared listener then sees customError and keeps your message instead of replacing it.
  • Do not show the browser's validationMessage for built-in problems: the browser writes it in the browser's language, not your page's.

Where to next

  • Bring your own validator — recipes with no extra package: reusable rules, required fields, error summaries, cross-field and server-side checks, translated messages.
  • Component pages — each form component's page documents the validation options specific to that control, such as the invalid state, min/max and blackout dates, accepted file types and sizes, and pattern: Input, Datepicker, File upload, OTP and Form field.