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.
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>
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-invalidis set on the inner control wheneveris-invalidis true, and removed when it is not.aria-describedbypoints at the hint and error. The component wires its own hint and error IDs to the inner control, alongside any IDs you set inaria-describedbyon 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 thehintslot.- 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, onlyvalidate('submit')). Without that gate a screen reader would announce a half-finished error on every keystroke. - The
is-invalidclass 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 theerrorslot) when you setis-invalid. - Move focus to the first invalid field on a failed submit. The components do not move focus for you.
- Give every control a
nameif you read the form withFormData, and a label:aegov-labelinside anaegov-form-field, or the component's ownlabelproperty 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>
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>
novalidateon 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 theaegovValidatelistener 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 seescustomErrorand keeps your message instead of replacing it. - Do not show the browser's
validationMessagefor 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/maxand blackout dates, accepted file types and sizes, andpattern: Input, Datepicker, File upload, OTP and Form field.