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 Components Form field

Form field

A Form field is a lightweight wrapper that pairs a label with a form control — an input, textarea, select, checkbox, range, progress bar, or one-time-password field — and links them automatically. "aegov-form-field" sets the label's "for" to the control's auto-generated id on mount and on every update, so there is no id to manage by hand. The wrapper itself adds no visual styling beyond a single layout block; surround it with your own form grid or stack rules.

input Layout
Status
Active
Introduced
4.0.x
View source code

Composing with different controls

Drop an aegov-label and a supported control inside aegov-form-field; the label's for is set to the control's field-id on mount and on every update — nothing to wire by hand.

Full name as on Emirates ID Reason for application Emirate of residence Abu Dhabi Dubai Sharjah I confirm that the information provided is true and accurate
<aegov-form-field>
  <aegov-label>Full name as on Emirates ID</aegov-label>
  <aegov-input placeholder="Your full legal name"></aegov-input>
</aegov-form-field>
<aegov-form-field>
  <aegov-label>Reason for application</aegov-label>
  <aegov-textarea placeholder="Briefly describe the purpose of your application." maxlength="500"></aegov-textarea>
</aegov-form-field>
<aegov-form-field>
  <aegov-label>Emirate of residence</aegov-label>
  <aegov-select placeholder="Select your emirate">
    <aegov-select-option value="abu-dhabi">Abu Dhabi</aegov-select-option>
    <aegov-select-option value="dubai">Dubai</aegov-select-option>
    <aegov-select-option value="sharjah">Sharjah</aegov-select-option>
  </aegov-select>
</aegov-form-field>
<aegov-form-field>
  <aegov-label>I confirm that the information provided is true and accurate</aegov-label>
  <aegov-checkbox></aegov-checkbox>
</aegov-form-field>

Composing a group

For aegov-checkbox-group and aegov-radio-group, skip aegov-form-field and name the group directly. Its own label property (rendered as the fieldset's <legend>) is the simplest option; aria-labelledby pointing at a plain heading beside it, as below, also works.

Which services do you need?

<h3 id="services-group-label" class="font-bold text-base">Which services do you need?</h3>
<div class="mt-2">
  <aegov-checkbox-group aria-labelledby="services-group-label">
    <aegov-checkbox field-id="cb-ff-visa" value="visa" label="Visa renewal"></aegov-checkbox>
    <aegov-checkbox field-id="cb-ff-license" value="license" label="Driving license"></aegov-checkbox>
  </aegov-checkbox-group>
</div>

Helper and error text

aegov-form-field is a layout wrapper — a plain paragraph you place inside it renders below the control, but is not linked to it. Put helper text in the control's hint (or its hint slot) instead; the control renders it below the field and links it with aria-describedby. A hint on the wrapper cascades to the control in the same way, and an element in the wrapper's own hint slot is linked to the control automatically. The hint stays visible while an error shows.

Email address
<aegov-form-field>
  <aegov-label>Email address</aegov-label>
  <aegov-input type="email" placeholder="name@example.ae" hint="We will use this address only to send service updates."></aegov-input>
</aegov-form-field>

Required fields

Set is-required="true" on the inner control — it drives real HTML5 validation (the native required attribute) on the control itself. Neither aegov-form-field nor aegov-label render a required-indicator asterisk automatically; add your own visible cue in the label's own text if your form needs one.

Emirates ID number *
<aegov-form-field>
  <aegov-label>Emirates ID number *</aegov-label>
  <aegov-input placeholder="784-XXXX-XXXXXXX-X" is-required="true"></aegov-input>
</aegov-form-field>

Variant

variant set on aegov-form-field cascades to the linked aegov-label and to the first form-control descendant, when that descendant has no explicit variant of its own.

Primary Secondary Neutral-max Neutral-min
<aegov-form-field variant="primary">
  <aegov-label>Primary</aegov-label>
  <aegov-input placeholder="Inherits primary"></aegov-input>
</aegov-form-field>
<aegov-form-field variant="secondary">
  <aegov-label>Secondary</aegov-label>
  <aegov-input placeholder="Inherits secondary"></aegov-input>
</aegov-form-field>
<aegov-form-field variant="neutral-max">
  <aegov-label>Neutral-max</aegov-label>
  <aegov-input placeholder="Inherits neutral-max"></aegov-input>
</aegov-form-field>
<aegov-form-field variant="neutral-min">
  <aegov-label>Neutral-min</aegov-label>
  <aegov-input placeholder="Inherits neutral-min"></aegov-input>
</aegov-form-field>

Composing with Card

A short group of form fields inside an aegov-card, for a self-contained step in a multi-step application.

Contact details

We'll use these to send updates about your application.

Email address Mobile number
<aegov-card appearance="light">
  <h3 class="font-bold text-lg m-0">Contact details</h3>
  <p class="text-base mt-2">We'll use these to send updates about your application.</p>
  <aegov-form-field extra-class="mt-4">
    <aegov-label>Email address</aegov-label>
    <aegov-input type="email" placeholder="name@example.ae"></aegov-input>
  </aegov-form-field>
  <aegov-form-field extra-class="mt-4">
    <aegov-label>Mobile number</aegov-label>
    <aegov-input type="tel" placeholder="+971 5X XXX XXXX"></aegov-input>
  </aegov-form-field>
</aegov-card>

RTL support

aegov-form-field is a thin block-level wrapper with no horizontal directional styling of its own — it renders identically in LTR and RTL. Wrap the form (or its container) with dir="rtl" and every linked label, control, and helper text follows the surrounding direction.

الاسم الكامل كما في الهوية الإماراتية إمارة الإقامة أبوظبي دبي الشارقة
<div dir="rtl">
  <aegov-form-field>
    <aegov-label>الاسم الكامل كما في الهوية الإماراتية</aegov-label>
    <aegov-input is-required="true" placeholder="الاسم الكامل"></aegov-input>
  </aegov-form-field>
  <aegov-form-field extra-class="mt-4">
    <aegov-label>إمارة الإقامة</aegov-label>
    <aegov-select placeholder="اختر الإمارة">
      <aegov-select-option value="abu-dhabi">أبوظبي</aegov-select-option>
      <aegov-select-option value="dubai">دبي</aegov-select-option>
      <aegov-select-option value="sharjah">الشارقة</aegov-select-option>
    </aegov-select>
  </aegov-form-field>
</div>

Usage

Here is the recommended usage of a form field on any website or application. These are recommended usage guides, however the developer must use the best practices of web and application development to accurately use this component.

Place exactly one label and one control inside each wrapper
If you need more than one input on a row, use multiple aegov-form-fields side by side rather than nesting extra controls in one — only the first matching control ever gets linked.

Put helper text in the control''s hint
Set hint (or fill the hint slot) on the control, or set hint (or fill the hint slot) on the wrapper. Either way it is linked with aria-describedby for you; a plain paragraph placed beside the control is not.

Use is-required on the control itself, not just visual styling
is-required="true" on the inner control drives real HTML5 validation (required on the native element) — it is the source of truth a form's own validation should key off, not a label convention alone.

Don't expect a required-field asterisk to appear automatically
Neither aegov-label nor aegov-form-field render a "*" for a required control — add your own visible indicator (e.g. appending an asterisk to the label's own text, or a "(required)" suffix) if your form needs one.

Don't compose aegov-checkbox-group or aegov-radio-group expecting an automatic label link
Automatic for/id linking only covers the control types listed in the "Supported controls" table above — neither group control is among them, because each renders its own <fieldset> and <legend>. Name the group with its own label property (or aria-labelledby pointing at a heading's id). The wrapper still cascades is-invalid, error-message, hint and variant to them.

API reference

The following are the properties and references of a form field

aegov-form-field properties

AttributeDescriptionTypeDefault

field-id

DOM id for the wrapper <div>. Auto-generated if omitted.

string

auto-generated

is-invalid

Wrapper-level invalid state. Cascades to the first form-control descendant if the child has not set its own value; setting it back to false clears what it cascaded.

boolean

false

error-message

Wrapper-level error message. Cascades to the first form-control descendant if the child has no own value; changing or clearing it updates the cascaded value.

string

""

hint

Wrapper-level hint text. Cascades to the first form-control descendant if the child has no own value; changing or clearing it updates the cascaded value.

string

""

variant

Colour family. Cascades to the linked aegov-label and to the first form-control descendant when that descendant has no explicit variant of its own.

primary | secondary | neutral-max | neutral-min

primary

extra-class

Additional CSS classes appended to the wrapper <div>.

string

none

Slots

SlotDescription

(default)

One aegov-label and one supported control. See the "Supported controls" table below for exactly which control types are recognised, and for which of the two behaviours (label linking, validation cascade) each one actually gets.

hint

Named hint slot, rendered below the control. Useful for rich hint markup instead of the plain-text hint prop. The wrapper gives the slotted element an id (if it has none) and adds it to the control's aria-describedby, so it is announced with the field.

Pass-through attributes

AttributeNotesForwards to

aria-*

Forwarded to the wrapper <div> — useful for role="group" plus aria-labelledby when grouping multiple controls.

wrapper <div>

data-*

Forwarded to the wrapper <div> — testing hooks, analytics tagging, or CSS targeting.

wrapper <div>

id

Not forwarded. Use field-id instead — it sets the wrapper's real id.

n/a

class, style

Stay on the <aegov-form-field> host — never forwarded inward. Use extra-class to extend the wrapper's classes.

host

Notes

The following notes are applicable of this component.

Built-in accessibility

  • After mount and on every update, the wrapper queries its slotted children for an aegov-label and a supported control (see the "Supported controls" table above). When both are present, the control's host gets its field-id as id and the label's for points at it, so clicking the label focuses the control.
  • Because <label for> cannot reach inside a control's shadow root, the wrapper also sets aria-label on the control from the label's text, as a screen reader would read it — content marked aria-hidden="true" (such as a decorative "*") is skipped — and keeps it in sync when the label text changes. An aria-label or aria-labelledby you set on the control yourself is never overwritten.
  • When the linked control is disabled (by its own is-disabled or an ancestor <fieldset disabled>), the label is dimmed to match.
  • The wrapper preserves user-set aria-*/data-* attributes via pass-through, so role="group" plus aria-labelledby can be added when grouping multiple controls.
  • The wrapper itself has no implicit ARIA role — assistive technology treats it as a plain <div>.

Developer responsibilities

  • Place exactly one aegov-label and one supported control inside each form-field. aegov-checkbox-group and aegov-radio-group never get a label link — name them with their own label property, or aria-labelledby (see "Composing a group" above).
  • For helper or error text, use the control's hint and error-message (or their slots), or set them (or the hint slot) on the wrapper — they are linked with aria-describedby automatically. A separate paragraph is not linked automatically.
  • Set is-required on the inner control for real HTML5 validation; add your own visible required-indicator in the label's text, since neither the label nor the wrapper render one automatically.
  • Do not nest one aegov-form-field inside another; with several controls in one wrapper, only the first is linked and receives the cascade.

Keyboard support

aegov-form-field introduces no keyboard behaviour of its own. All keyboard interaction is handled by the inner control — refer to that control's own documentation for its keyboard map.