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 Dropdowns
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Components Checkbox

Checkbox

A Checkbox lets a user toggle a single binary choice, or select any number of options from a related set. "aegov-checkbox" handles the individual control — label, hint, states, sizes, and colour variants — while "aegov-checkbox-group" wraps a set of checkboxes in a native "fieldset", adding shared orientation, appearance, a select-all controller with automatic indeterminate cascading, and group-level validation.

input Interactive
Status
Active
Introduced
4.0.x
View source code

Anatomy

aegov-checkbox renders a native <input type="checkbox">, optionally wrapped in a <label> when label is set, with the hint and error message as sibling regions. aegov-checkbox-group renders a native <fieldset>/<legend> around a set of checkboxes, plus its own shared hint and error regions.

Image showing anatomy of a checkbox

Item Name Description
1 Control The native checkbox input — square, checked/unchecked/indeterminate
2 Label Clickable text describing the option (label prop)
3 Hint Supporting helper text shown below the label — stays visible while an error shows
4 Error message Shown after the hint once is-invalid is set
5 Legend (group only) The group's own accessible name, from aegov-checkbox-group's label

Label and hint

Set label to render a clickable <label> around the control. Add hint for supporting helper text underneath — it stays visible while a validation error shows, because that is when the user needs it most. Omit label entirely for a bare checkbox (for example, inside a table row with its own column heading) and supply your own aria-label instead.

<aegov-checkbox field-id="cb-label-1" label="Send me product updates"></aegov-checkbox>
<aegov-checkbox field-id="cb-label-2" label="Share anonymised usage data" hint="Helps us prioritise fixes. You can opt out at any time."></aegov-checkbox>
<aegov-checkbox field-id="cb-label-3" aria-label="Select this row"></aegov-checkbox>

States

A checkbox can be checked, unchecked, disabled (in either checked state), required, or indeterminate. Indeterminate is usually set programmatically by a parent group's select-all logic (see Select all) rather than authored directly, but it can be set on load the same way any other state prop can.

<aegov-checkbox field-id="cb-state-1" label="Checked" is-checked="true"></aegov-checkbox>
<aegov-checkbox field-id="cb-state-2" label="Unchecked"></aegov-checkbox>
<aegov-checkbox field-id="cb-state-3" label="Disabled" is-disabled="true"></aegov-checkbox>
<aegov-checkbox field-id="cb-state-4" label="Disabled, checked" is-disabled="true" is-checked="true"></aegov-checkbox>
<aegov-checkbox field-id="cb-state-5" label="Required" is-required="true"></aegov-checkbox>
<aegov-checkbox field-id="cb-state-6" label="Indeterminate" is-indeterminate="true"></aegov-checkbox>

Sizes

size accepts five tokens, from xs up to xl. It scales the control, the label text, and the hint text together, and — like Badge, Banner, and Callout — accepts a responsive breakpoint string (e.g. size="sm md:base").

<aegov-checkbox field-id="cb-size-xs" size="xs" label="Extra small"></aegov-checkbox>
<aegov-checkbox field-id="cb-size-sm" size="sm" label="Small"></aegov-checkbox>
<aegov-checkbox field-id="cb-size-base" size="base" label="Base (default)"></aegov-checkbox>
<aegov-checkbox field-id="cb-size-lg" size="lg" label="Large"></aegov-checkbox>
<aegov-checkbox field-id="cb-size-xl" size="xl" label="Extra large"></aegov-checkbox>

Variant

variant selects the colour family for the rest border, checked fill, and focus outline. On aegov-checkbox-group, setting variant cascades it to every child that hasn't set its own.

Variant Rest border / accent Checked fill
primary primary-600 primary-600
secondary secondary-600 secondary-600
neutral-max aeblack-800 aeblack-800
neutral-min aeblack-400 aeblack-400

Variant example

<aegov-checkbox field-id="cb-variant-primary" variant="primary" is-checked="true" label="Primary"></aegov-checkbox>
<aegov-checkbox field-id="cb-variant-secondary" variant="secondary" is-checked="true" label="Secondary"></aegov-checkbox>
<aegov-checkbox field-id="cb-variant-neutral-max" variant="neutral-max" is-checked="true" label="Neutral-max"></aegov-checkbox>
<aegov-checkbox field-id="cb-variant-neutral-min" variant="neutral-min" is-checked="true" label="Neutral-min"></aegov-checkbox>

Group basics

aegov-checkbox-group wraps related checkboxes in a native <fieldset>. Set label for the group's <legend>, and give each child a value so aegovCheckboxGroupChange reports which ones are checked.

<aegov-checkbox-group label="Notification preferences">
  <aegov-checkbox field-id="cb-group-email" value="email" label="Email"></aegov-checkbox>
  <aegov-checkbox field-id="cb-group-sms" value="sms" label="SMS"></aegov-checkbox>
  <aegov-checkbox field-id="cb-group-push" value="push" label="Push notification"></aegov-checkbox>
</aegov-checkbox-group>

Orientation

orientation stacks the group's items vertically (default) or lets them wrap horizontally — useful for a compact set of short options.

<aegov-checkbox-group label="Vertical (default)" orientation="vertical">
  <aegov-checkbox field-id="cb-orient-v1" value="mon" label="Monday"></aegov-checkbox>
  <aegov-checkbox field-id="cb-orient-v2" value="tue" label="Tuesday"></aegov-checkbox>
  <aegov-checkbox field-id="cb-orient-v3" value="wed" label="Wednesday"></aegov-checkbox>
</aegov-checkbox-group>
<aegov-checkbox-group label="Horizontal" orientation="horizontal">
  <aegov-checkbox field-id="cb-orient-h1" value="mon" label="Monday"></aegov-checkbox>
  <aegov-checkbox field-id="cb-orient-h2" value="tue" label="Tuesday"></aegov-checkbox>
  <aegov-checkbox field-id="cb-orient-h3" value="wed" label="Wednesday"></aegov-checkbox>
</aegov-checkbox-group>

Appearance

appearance, set on aegov-checkbox-group, cascades a visual layout to every child checkbox — list adds separator lines, cards turns each item into a bordered card, and pills renders a toggle-chip. A standalone aegov-checkbox outside any group always renders default; appearance is not meant to be set on it directly.

<aegov-checkbox-group label="Default" appearance="default">
  <aegov-checkbox field-id="cb-app-def-1" value="std" label="Standard"></aegov-checkbox>
  <aegov-checkbox field-id="cb-app-def-2" value="exp" label="Express"></aegov-checkbox>
</aegov-checkbox-group>
<aegov-checkbox-group label="List" appearance="list">
  <aegov-checkbox field-id="cb-app-list-1" value="std" label="Standard"></aegov-checkbox>
  <aegov-checkbox field-id="cb-app-list-2" value="exp" label="Express"></aegov-checkbox>
</aegov-checkbox-group>
<aegov-checkbox-group label="Cards" appearance="cards">
  <aegov-checkbox field-id="cb-app-cards-1" value="std" label="Standard"></aegov-checkbox>
  <aegov-checkbox field-id="cb-app-cards-2" value="exp" label="Express"></aegov-checkbox>
</aegov-checkbox-group>
<aegov-checkbox-group label="Pills" appearance="pills" orientation="horizontal">
  <aegov-checkbox field-id="cb-app-pills-1" value="std" label="Standard"></aegov-checkbox>
  <aegov-checkbox field-id="cb-app-pills-2" value="exp" label="Express"></aegov-checkbox>
</aegov-checkbox-group>

Select all

Mark one checkbox in a group is-check-all to turn it into a select-all controller. It automatically checks or unchecks every other (enabled) checkbox in the group, and reflects back to indeterminate whenever only some — but not all — of them are checked. This cascades in both directions: toggling the controller toggles the children, and toggling any child updates the controller.

<aegov-checkbox-group label="Select services">
  <aegov-checkbox field-id="cb-selectall" is-check-all="true" label="Select all"></aegov-checkbox>
  <aegov-checkbox field-id="cb-svc-visa" value="visa" label="Visa renewal"></aegov-checkbox>
  <aegov-checkbox field-id="cb-svc-license" value="license" label="Driving license"></aegov-checkbox>
  <aegov-checkbox field-id="cb-svc-id" value="id" label="Emirates ID"></aegov-checkbox>
</aegov-checkbox-group>

Group disabled

Set is-disabled on aegov-checkbox-group to disable every checkbox inside it at once — the group both wraps its own <fieldset disabled> and cascades is-disabled to each child's own prop, so no need to set it individually. Toggling the group's is-disabled back off restores each child's own is-disabled setting, so a child that was disabled on its own stays disabled.

<aegov-checkbox-group label="Add-ons (unavailable on this plan)" is-disabled="true">
  <aegov-checkbox field-id="cb-disabled-1" value="priority" label="Priority support"></aegov-checkbox>
  <aegov-checkbox field-id="cb-disabled-2" value="backup" label="Daily backups" is-checked="true"></aegov-checkbox>
</aegov-checkbox-group>

Composing with Card

A checkbox group drops into an aegov-card like any other content, for a self-contained selectable panel — useful for a pricing add-ons block or a settings section.

Choose your add-ons

Select any extra services to include with your application.

<aegov-card appearance="light">
  <h3 class="font-bold text-lg m-0">Choose your add-ons</h3>
  <p class="text-base mt-2 mb-4">Select any extra services to include with your application.</p>
  <aegov-checkbox-group>
    <aegov-checkbox field-id="cb-card-1" value="priority" label="Priority support"></aegov-checkbox>
    <aegov-checkbox field-id="cb-card-2" value="backup" label="Daily backups"></aegov-checkbox>
    <aegov-checkbox field-id="cb-card-3" value="sms" label="SMS confirmations"></aegov-checkbox>
  </aegov-checkbox-group>
</aegov-card>

RTL support

Both components are direction-agnostic: label/hint/error placement and the group's <fieldset>/<legend> layout follow logical properties automatically, no extra configuration needed. One narrow exception is purely cosmetic — the checkbox's hover halo effect uses a translateX that would otherwise sit off-centre in RTL; a dedicated :host-context([dir="rtl"])/:host(:dir(rtl)) rule flips it back to centred. You never need to do anything for this yourself; it's handled internally.

<div dir="rtl">
  <aegov-checkbox-group label="خدمات التطبيق">
    <aegov-checkbox field-id="cb-rtl-1" value="visa" label="تجديد التأشيرة"></aegov-checkbox>
    <aegov-checkbox field-id="cb-rtl-2" value="license" label="رخصة القيادة" hint="يشمل التجديد والاستبدال."></aegov-checkbox>
    <aegov-checkbox field-id="cb-rtl-3" value="id" label="الهوية الإماراتية" is-checked="true"></aegov-checkbox>
  </aegov-checkbox-group>
</div>

Usage

Here is the recommended usage of a checkbox 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.

Use a checkbox group for related multi-select options, not a row of standalone checkboxes
Wrapping related checkboxes in aegov-checkbox-group gives them a shared accessible name via <legend>, consistent spacing, and aggregate validation — a row of unrelated standalone aegov-checkbox elements gets none of that for free.

Let is-check-all manage indeterminate state — don't set it manually per interaction
The select-all controller already recalculates checked/unchecked/indeterminate automatically as children change. Manually toggling is-indeterminate yourself will fight the group's own logic.

Keep variant consistent within one group
Set variant once on the aegov-checkbox-group and let it cascade, rather than repeating the same value on every child — it's less to keep in sync if the group's colour ever changes.

Do not use a checkbox for a single yes/no setting that takes effect immediately
A checkbox implies "part of a form, submitted later." For an instantly-applied binary toggle (dark mode, notifications on/off), use a toggle/switch component instead so the interaction model matches user expectation.

API reference

The following are the properties and references of a checkbox

aegov-checkbox default properties

AttributeDescriptionTypeDefault

field-id

DOM id reflected on the inner native <input>. Auto-generated if omitted.

string

auto-generated

name

Form field name. Reflected on the host so ElementInternals can read it for native form submission — the value is read from the host, not the inner shadow-DOM <input>.

string

(none)

value

Value submitted with the form when checked. Falls back to on if left unset, matching native checkbox behaviour.

string

(none)

is-checked

Whether the checkbox is checked.

boolean

false

is-indeterminate

Visual + aria-checked="mixed" indeterminate state. Cleared automatically the moment a user interacts with the control. Normally set programmatically by a parent group's select-all logic (see Select all) rather than authored directly.

boolean

false

size

Size token. Accepts a responsive breakpoint string the same way Badge/Banner/Callout do, e.g. "sm md:base".

xs | sm | base | lg | xl

base

variant

Colour family for the rest border, checked fill, and focus outline.

primary | secondary | neutral-max | neutral-min

primary

appearance

Visual layout set by a parent aegov-checkbox-group (default/cards/pills). Not meant to be set directly on a standalone checkbox — see Appearance.

default | cards | pills

default

is-disabled

Whether the checkbox is disabled.

boolean

false

is-required

Whether the checkbox must be checked for the form to submit.

boolean

false

label

Label text. When provided, an associated <label> wraps the control so clicking the text also toggles it. When omitted, only the bare <input> renders — supply your own visible or aria-label labelling.

string

(none)

hint

Helper text shown below the label. Only rendered when label is set. It stays visible while an error shows — the error renders after it and both are announced as the description. Use the hint slot instead for rich markup.

string

(none)

is-check-all

Marks this checkbox as the "select all" controller within a parent aegov-checkbox-group. See Select all.

boolean

false

is-invalid

Visual + aria-invalid invalid state.

boolean

false

error-message

Inline error message shown when is-invalid is set. Use the error slot for rich markup instead.

string

''

extra-class

Additional CSS classes applied to the internal wrapper.

string

(none)

This component renders inside a real shadow DOM, so extra-class only applies margin/padding (spacing) utilities — e.g. mt-4, md:px-6. Colour, border, typography, and every other visual utility are silently ignored: this is an isolated component whose internal styles can't be overridden, keeping it visually consistent wherever it's used.

aegov-checkbox-group default properties

AttributeDescriptionTypeDefault

appearance

Layout for the whole group. list adds separator lines between items; cards/pills restyle each child checkbox (cascaded down to every child, see Appearance).

default | list | cards | pills

default

orientation

Stack direction for checkbox items.

vertical | horizontal

vertical

label

Rendered as the group's <legend> for accessibility.

string

(none)

size

Applied to every child checkbox, overriding any size a child sets itself — set size once on the group. Accepts a responsive breakpoint string.

xs | sm | base | lg | xl

base

variant

Cascades to every child checkbox that hasn't set its own variant.

primary | secondary | neutral-max | neutral-min

primary

is-disabled

Disables every checkbox in the group via a native <fieldset disabled>.

boolean

false

is-required

Aggregate-level only — validates that at least one child checkbox is checked. Does not mark individual children as required, and the browser does not enforce it on form submission — check it with validate() or aegovValidate on submit. Adds a visible * to the legend plus a visually hidden "(required)" for screen readers, since a fieldset cannot carry aria-required.

boolean

false

is-invalid

Visual + aria-invalid invalid state on the group's <fieldset>.

boolean

false

error-message

Inline error shown below the group when is-invalid is set. Use the error slot for rich markup.

string

''

hint

Helper text shown below the group's items. Stays visible while an error shows — the error renders after it. Use the hint slot for rich markup.

string

''

extra-class

Additional CSS classes applied to the internal fieldset wrapper.

string

(none)

This component renders inside a real shadow DOM, so extra-class only applies margin/padding (spacing) utilities — e.g. mt-4, md:px-6. Colour, border, typography, and every other visual utility are silently ignored: this is an isolated component whose internal styles can't be overridden, keeping it visually consistent wherever it's used.

Events

EventDescriptionComponentDetail

aegovCheckboxChange

Fired when a single checkbox's checked state changes.

aegov-checkbox

{ checked: boolean; value?: string }

aegovCheckboxGroupChange

Fired whenever any child checkbox in the group changes. Carries every currently-checked value.

aegov-checkbox-group

{ values: string[] }

aegovValidate

Unified validation event, fired on blur, change, and manual validate() calls.

both

AegovValidationDetail<boolean> (checkbox) / AegovValidationDetail<string[]> (group)

Methods

MethodDescriptionComponent

validate(trigger?)

Imperatively re-runs validation and emits aegovValidate. Returns Promise<{ valid, message, validity }>.

both

setCustomValidity(message)

Mirrors HTMLInputElement.setCustomValidity(). An empty string clears the custom error.

both

Slots

SlotDescriptionComponent

(default)

The checkbox items themselves.

aegov-checkbox-group

hint

Rich markup for the hint, in place of the plain-text hint prop.

both

error

Rich markup for the error message, in place of the plain-text error-message prop.

both

Pass-through attributes

AttributeNotesForwards to

aria-*

Forwarded automatically, except aria-invalid (owned internally). Your aria-describedby is kept and combined with the hint/error ids. aria-required is also owned internally on the group.

inner <input> (checkbox) / <fieldset> (group)

data-*

Forwarded automatically on both components.

inner <input> (checkbox) / <fieldset> (group)

form, tabindex, title

Forwarded on aegov-checkbox only. Not forwarded by aegov-checkbox-group.

inner <input>

autofocus

Forwarded on aegov-checkbox only, including the bare boolean-attribute shorthand (<aegov-checkbox autofocus>).

inner <input>

id

Not forwarded on either component. Use field-id to control the checkbox's real inner id.

n/a

class, style

Applied to the host element on both components — stays host-only, never forwarded inward.

host

Notes

The following notes are applicable of this component.

Built-in accessibility

  • aegov-checkbox renders a real native <input type="checkbox">, so keyboard toggling (Space), focus handling, and assistive-technology announcements all come for free.
  • Setting label wraps the input in a real <label>, so clicking or tapping the text also toggles the control — no manual for/id wiring needed.
  • is-indeterminate sets the native indeterminate DOM property (not just a visual style) and reflects aria-checked="mixed", so screen readers announce the true tri-state correctly.
  • aegov-checkbox-group renders a native <fieldset>/<legend> pair when label is set, giving the whole group a single accessible name without extra ARIA wiring.
  • Hint and error text are wired to the input (or fieldset) via aria-describedby automatically whenever hint/error-message (or their slots) are present — you never need to manage the id linkage yourself. The hint stays visible while an error shows, so the description reads the error, then the hint.
  • The error region only takes role="alert" after the user has actually interacted with the field once (blurred it, or interacted with the group), so a validation message present at initial page load is not announced as an interruption.

Developer responsibility

The following is required for a developer to add additionally or pay attention to regarding this component.

  • If you omit label (for example, a checkbox inside a data-table row with a visible column heading), supply aria-label or aria-labelledby yourself — the component does not fall back to any other accessible name.
  • When using is-check-all, give it its own descriptive label (e.g. "Select all services") — its relationship to the other items is conveyed by DOM position and indeterminate state, not announced automatically.
  • is-indeterminate is a visual/state hint only, never a substitute for is-required or real validation — a required checkbox group still needs at least one real checked value to pass validation.
  • is-required on aegov-checkbox-group does not block a native form submit, and it shows no error by itself: the group isn't part of the browser's form validation. On submit, call await group.validate('submit'); if the result isn't valid, prevent the submit, set error-message (for example from result.message) and is-invalid on the group, and move focus to the first checkbox in the group. Clear them when the user makes a choice. See the whole-form validation pattern.
  • Check colour contrast for any custom extra-class background or text colour against your chosen variant — the component does not validate this for you.

Additional notes

  • size on both components accepts a responsive breakpoint string, the same convention used by Badge, Banner, and Callout (e.g. size="sm md:base").
  • appearance on aegov-checkbox is written by its parent group and shouldn't be set directly — set appearance on the aegov-checkbox-group instead. A standalone checkbox with no parent group always renders default.
  • name/form submission are handled via ElementInternals on the host element, not the inner shadow-DOM <input> — reading checkbox.name or checking form data works exactly like a native input, but querying the shadow DOM's own <input> for name will come back empty. This is expected, not a bug.

Keyboard support

Key Function
Tab Moves focus to the next checkbox (or the next focusable element after the group).
Shift + Tab Moves focus to the previous focusable element.
Space Toggles the focused checkbox's checked state. Clears any indeterminate state.