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 Datepicker

Datepicker

A Datepicker lets a user pick a single date, or a start and end date for a range, from a calendar dialog instead of typing free text. "aegov-datepicker" renders a read-only trigger input and opens its calendar in a portal attached to the end of the page, so the calendar is never clipped by a card, modal, or any other "overflow: hidden" ancestor. Single-date and date-range selection share one component, with full keyboard navigation, presets, blackout dates, range limits, and an optional Apply / Cancel confirmation flow.

input Interactive
Status
Active
Introduced
4.0.x
View source code

Anatomy

aegov-datepicker renders a styled trigger — one input in single mode, two in range mode — plus a calendar dialog that opens in a portal at the end of document.body, not inline in the surrounding layout.

Image showing anatomy of a datepicker

Item Name Description
1 Trigger input Read-only text input(s) showing the formatted value
2 Calendar icon Decorative, aria-hidden
3 Clear button Shown once a value is set (is-clearable, default on)
4 Calendar dialog Portaled role="dialog", positioned relative to the trigger
5 Header Prev/next navigation plus month/year selects (or a static label)
6 Day grid role="grid" of selectable day buttons
7 Presets sidebar (range only) One-click range shortcuts, when presets is set
8 Footer (optional) Apply / Cancel buttons, when is-with-confirmation is set

Single date

The default appearance="single" collects one date. Clicking a day commits the selection, fires aegovDatepickerChange, and closes the calendar.

Date of birth
<aegov-form-field>
  <aegov-label>Date of birth</aegov-label>
  <aegov-datepicker format="DD MMM YYYY" is-disable-future="true"></aegov-datepicker>
</aegov-form-field>

Date range

Set appearance="range" to render two trigger inputs — start and end — and a side-by-side two-month calendar. The first click marks the start, the second marks the end. Clicking a day before the existing start swaps the two automatically.

Stay dates
<aegov-form-field>
  <aegov-label>Stay dates</aegov-label>
  <aegov-datepicker appearance="range" label-range-start="Check-in" label-range-end="Check-out" format="DD MMM YYYY"></aegov-datepicker>
</aegov-form-field>

Output format

format controls how the selected date renders into the trigger and into the value string emitted with each change. The default is YYYY-MM-DD.

Token Output Example
YYYY 4-digit year 2026
YY 2-digit year 26
MMMM Full month name September
MMM Short month name Sep
MM 2-digit month 09
M Numeric month 9
DD 2-digit day 08
D Numeric day 8
ddd Full weekday Tuesday
dd Short weekday Tue
Date (DD MMM YYYY) Date (MMMM D, YYYY) Date (YYYY-MM-DD)
<aegov-form-field>
  <aegov-label>Date (DD MMM YYYY)</aegov-label>
  <aegov-datepicker format="DD MMM YYYY" placeholder="DD MMM YYYY"></aegov-datepicker>
</aegov-form-field>
<aegov-form-field>
  <aegov-label>Date (MMMM D, YYYY)</aegov-label>
  <aegov-datepicker format="MMMM D, YYYY" placeholder="MMMM D, YYYY"></aegov-datepicker>
</aegov-form-field>
<aegov-form-field>
  <aegov-label>Date (YYYY-MM-DD)</aegov-label>
  <aegov-datepicker format="YYYY-MM-DD" placeholder="YYYY-MM-DD"></aegov-datepicker>
</aegov-form-field>

Minimum and maximum dates

min and max constrain the selectable range. Both accept an ISO date string or the literal today. is-disable-future="true" is a shorthand for max="today".

Emirates ID issue date Appointment date
<aegov-form-field>
  <aegov-label>Emirates ID issue date</aegov-label>
  <aegov-datepicker is-disable-future="true" format="DD MMM YYYY"></aegov-datepicker>
</aegov-form-field>
<aegov-form-field>
  <aegov-label>Appointment date</aegov-label>
  <aegov-datepicker min="today" format="DD MMM YYYY"></aegov-datepicker>
</aegov-form-field>

Blackout dates

Pass a comma-separated list of ISO dates to blackout. Listed days are visually muted, marked aria-disabled, and cannot be picked — useful for closed days or fully booked slots. A value set from code that lands on a blackout date makes the field invalid (customError), with a message such as "15 Sep 2026 is not available. Choose another date" in the datepicker's UI language. blackout only accepts an explicit date list; it has no recurring-pattern syntax.

Service appointment date
<aegov-form-field>
  <aegov-label>Service appointment date</aegov-label>
  <aegov-datepicker min="today" blackout="2026-09-15,2026-09-16,2026-09-22" format="DD MMM YYYY"></aegov-datepicker>
</aegov-form-field>

Range constraints

In range mode, min-range and max-range cap how many days the selection may span. While the user chooses the end date (mouse hover or keyboard focus), an out-of-limit preview turns red and a message such as "Range must be at least 3 days" shows under the months and is announced. A second click that would violate the limit is refused with the same message, and the start date stays. Pair this with a hint stating the allowed range up front.

Leave dates
<aegov-form-field>
  <aegov-label>Leave dates</aegov-label>
  <aegov-datepicker appearance="range" label-range-start="Leave start" label-range-end="Leave end" min-range="2" max-range="14" hint="Choose between 2 and 14 days" format="DD MMM YYYY"></aegov-datepicker>
</aegov-form-field>

Presets

In range mode, presets renders a sidebar of one-click range shortcuts. Pass a comma-separated list of preset ids. Supported ids: today, yesterday, tomorrow, thisWeek, lastWeek, nextWeek, last7Days, next7Days, last14Days, next14Days, last30Days, next30Days, thisMonth, lastMonth, nextMonth, last3Months, next3Months, last6Months, next6Months, thisQuarter, lastQuarter, nextQuarter, thisYear, lastYear, nextYear, yearToDate, allTime.

Report period
<aegov-form-field>
  <aegov-label>Report period</aegov-label>
  <aegov-datepicker appearance="range" presets="today,yesterday,last7Days,thisMonth,lastMonth" label-range-start="From" label-range-end="To" format="DD MMM YYYY"></aegov-datepicker>
</aegov-form-field>

Apply / Cancel confirmation

Set is-with-confirmation="true" to render Apply and Cancel buttons in the calendar footer. While the calendar is open, clicks build a pending selection that only commits to the trigger on Apply. Cancel and outside clicks discard the pending state without firing a change event.

Booking dates
<aegov-form-field>
  <aegov-label>Booking dates</aegov-label>
  <aegov-datepicker appearance="range" is-with-confirmation="true" label-range-start="Start" label-range-end="End" format="DD MMM YYYY"></aegov-datepicker>
</aegov-form-field>

Week start day

start-day sets the first column of the calendar grid — 0 Sunday (default), 1 Monday, 6 Saturday. UAE working-week conventions typically use 1 or 6.

Week starts Monday Week starts Saturday
<aegov-form-field>
  <aegov-label>Week starts Monday</aegov-label>
  <aegov-datepicker start-day="1"></aegov-datepicker>
</aegov-form-field>
<aegov-form-field>
  <aegov-label>Week starts Saturday</aegov-label>
  <aegov-datepicker start-day="6"></aegov-datepicker>
</aegov-form-field>

Header style

is-header-selectable (default true) renders month and year dropdowns in the calendar header so the user can jump quickly. Set it false for a static month-year label with only chevron navigation. Pair with year-range-start / year-range-end to bound the year dropdown — useful for a date-of-birth field.

Date Date of birth
<aegov-form-field>
  <aegov-label>Date</aegov-label>
  <aegov-datepicker is-header-selectable="false"></aegov-datepicker>
</aegov-form-field>
<aegov-form-field>
  <aegov-label>Date of birth</aegov-label>
  <aegov-datepicker year-range-start="1925" year-range-end="2026" is-disable-future="true"></aegov-datepicker>
</aegov-form-field>

Disabled and required

Set is-disabled="true" to lock the trigger and prevent the calendar from opening. Set is-required="true" to mark the field required and forward required to the inner input.

Application date Submitted on
<aegov-form-field>
  <aegov-label>Application date</aegov-label>
  <aegov-datepicker is-required="true"></aegov-datepicker>
</aegov-form-field>
<aegov-form-field>
  <aegov-label>Submitted on</aegov-label>
  <aegov-datepicker is-disabled="true" value="2026-05-01" format="DD MMM YYYY"></aegov-datepicker>
</aegov-form-field>

Sizes

size scales the trigger input — xs, sm, base (default), lg, xl. Accepts a responsive breakpoint string, the same convention used by aegov-input.

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

Variant

variant selects the colour family for the trigger's idle border, the selected day fill, the today indicator, and the hover background. The focus ring uses the variant's own support colour (primary-support-500 / secondary-support-500 / seablue-500 for both neutral variants, one step lighter in dark mode); the error border stays aered-600 regardless of variant.

Variant Idle border Selected day fill Today text Hover background
primary primary-600 primary-600 primary-600 primary-100
secondary secondary-600 secondary-600 secondary-700 secondary-100
neutral-max aeblack-800 aeblack-800 aeblack-800 aeblack-100
neutral-min aeblack-400 aeblack-800 aeblack-800 aeblack-50

neutral-min keeps the trigger's idle border quiet (aeblack-400) but the selected-day fill deliberately stays dark (aeblack-800) rather than using its own light token, so the calendar's checked state remains legible even for the lightest variant.

Variant example

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

Custom trigger

The trigger slot replaces the default input with any focusable element — useful for an icon-only button or another custom launcher. The component still owns open/close state and positioning; the slotted element only needs to be focusable.

Pick a date
<aegov-datepicker>
  <aegov-button slot="trigger" appearance="outline">Pick a date</aegov-button>
</aegov-datepicker>

RTL support

When the host (or an ancestor) is dir="rtl", the portaled calendar mirrors its layout: the second calendar in range mode swaps sides, the presets sidebar moves to the opposite edge, and the prev/next chevron icons swap so they still point in the reading direction. Without locale, month and weekday names and the datepicker's own text follow the page language — the nearest lang, or dir="rtl" when no lang is set — so an Arabic page gets Arabic text throughout; locale="ar" forces it. Left/Right arrow keys follow the visual direction, and the calendar portal carries the same dir and lang. Add start-day="6" to match the UAE week convention.

فترة التقرير
<div dir="rtl" lang="ar">
  <aegov-form-field>
    <aegov-label>فترة التقرير</aegov-label>
    <aegov-datepicker appearance="range" locale="ar" start-day="6" presets="today,last7Days,thisMonth,lastMonth" label-range-start="من" label-range-end="إلى" format="D MMMM YYYY"></aegov-datepicker>
  </aegov-form-field>
</div>

Usage

Here is the recommended usage of a datepicker 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 is-disable-future for backward-looking fields
For a date of birth, document issue date, or "date this happened" field, is-disable-future="true" reads clearer than a manually computed max="today", and it never drifts out of date.

Always give the field a visible label
Placeholder text and label-range-start / label-range-end disappear visually once a value is filled in. Wrap every datepicker in aegov-form-field with an aegov-label, as in the examples on this page, rather than relying on the placeholder.

Match start-day and locale together for Arabic contexts
Pair locale="ar" with start-day="6" (Saturday) so the calendar's week layout matches the UAE convention users already expect, rather than leaving the default Sunday start.

Offer presets for reporting or analytics ranges
When a range field maps to a common reporting period ("Last 30 days", "This quarter"), configure presets so the user can pick it in one click instead of two manual day-clicks.

Do not expect blackout to express recurring rules
blackout is a literal comma-separated list of exact dates — it has no concept of "every weekend" or "every Friday". Enumerate every excluded date individually.

Do not leave range limits for users to discover by failing
A second click that would violate min-range / max-range is refused with a message under the months — but users only see it after trying. Set a clear hint describing the allowed range up front.

API reference

The following are the properties and references of a datepicker

aegov-datepicker properties

PropertyAttributeDescriptionTypeDefault

appearance

appearance

Selection mode — single date or date range.

single | range

single

value

value

Pre-selected value. Single: "YYYY-MM-DD". Range: "YYYY-MM-DD / YYYY-MM-DD".

string

''

format

format

Output and display format built from calendar tokens (see Output format).

string

YYYY-MM-DD

placeholder

placeholder

Placeholder for the single-mode input. Empty defaults to "Select date" in the UI language (see locale).

string

''

labelRangeStart

label-range-start

Placeholder for the range-mode start input. Empty defaults to "Start date" in the UI language (see locale).

string

''

labelRangeEnd

label-range-end

Placeholder for the range-mode end input. Empty defaults to "End date" in the UI language (see locale).

string

''

min

min

Minimum selectable date — an ISO date string, or the literal today.

string

''

max

max

Maximum selectable date — an ISO date string, or the literal today.

string

''

isDisableFuture

is-disable-future

Shorthand for max="today" — disables every date after today.

boolean

false

startDay

start-day

First weekday column of the calendar grid. 0 Sunday … 6 Saturday.

number

0

locale

locale

BCP 47 locale for month and weekday names and formatted dates (e.g. en, ar-AE, fr); when it is not set, dates follow the page language, like the built-in text. An Arabic or English locale (ar, ar-*, en, en-*) also sets the language of all the datepicker's own text — placeholders, buttons, presets, validation messages and screen-reader text. With no locale, or any other locale, that text follows the page language: the nearest ancestor lang (Arabic for ar/ar-*, English otherwise) or, when no lang is set, the nearest dir (rtl = Arabic). Layout direction always follows dir.

string

undefined

minRange

min-range

Minimum number of days a range selection must span. 0 = unconstrained.

number

0

maxRange

max-range

Maximum number of days a range selection may span. 0 = unlimited.

number

0

blackout

blackout

Comma-separated list of exact ISO dates that cannot be selected. A value set from code that falls on one is invalid (customError, with its own message).

string

''

presets

presets

Comma-separated preset ids rendered as a sidebar of range shortcuts (range mode only — see Presets).

string

''

isDisabled

is-disabled

Disables the trigger and prevents the calendar from opening.

boolean

false

isRequired

is-required

Marks the field as required for form validation and forwards required to the inner input.

boolean

false

isClearable

is-clearable

Shows a clear button once a value is set.

boolean

true

isHeaderSelectable

is-header-selectable

Renders month / year select dropdowns in the calendar header. Set false for a static label with only chevron navigation.

boolean

true

yearRangeStart

year-range-start

First year in the year dropdown. Used only when year-range-end is also set; otherwise the dropdown spans the displayed year ± 100.

number

0

yearRangeEnd

year-range-end

Last year in the year dropdown. Used only when year-range-start is also set; otherwise the dropdown spans the displayed year ± 100.

number

0

isWithConfirmation

is-with-confirmation

Renders Apply / Cancel buttons in the calendar footer; the selection only commits on Apply.

boolean

false

size

size

Trigger size token. Accepts a single token or a responsive breakpoint string.

xs | sm | base | lg | xl

base

variant

variant

Colour family for the trigger border, selected day fill, today indicator, and hover background. The focus ring follows the variant's support colour; the error border stays red regardless of variant (see Variant).

primary | secondary | neutral-max | neutral-min

primary

fieldId

field-id

Unique field ID. Auto-generated if omitted; used to derive hint/error ids.

string

generated

name

name

Form field name for ElementInternals submission. Range mode submits as name-start / name-end.

string

undefined

isInvalid

is-invalid

Visual and accessible invalid state.

boolean

false

errorMessage

error-message

Inline error message. Use the error slot for rich markup instead.

string

''

hint

hint

Helper hint shown below the trigger. It stays visible while an error shows — the error renders above it and both are announced as the description. Use the hint slot for rich markup instead.

string

''

Slots

SlotDescription

trigger

Replaces the default input with any focusable element (e.g. an icon button). The component still owns open/close state and positioning, and sets aria-haspopup="dialog" and aria-expanded on it. No value, placeholder or clear button is rendered — show the chosen date in the trigger yourself.

hint

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

error

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

Events

EventDetailFires when

aegovDatepickerChange

{ value, date, startDate?, endDate? }

The value commits — single click in single mode, second click (or Apply) in range mode, a preset click, or clear().

aegovDatepickerOpen

void

The calendar opens.

aegovDatepickerClose

void

The calendar closes, for any reason (selection, Cancel, outside click, Escape).

aegovDatepickerClear

void

The clear button is clicked, or clear() is called.

aegovDatepickerMonthChange

{ month, year }

The visible month or year changes through the Previous/Next buttons or the month/year selects. Not fired when keyboard focus moves into another month, or when a preset is chosen.

aegovValidate

AegovValidationDetail

The user picks or clears a value (trigger change), the field loses focus (blur), or validate() is called. Values set from code, or restored by a form reset, fire no event.

Methods

MethodReturnsDescription

open()

Promise<void>

Opens the calendar. No-op while is-disabled. Works from a button elsewhere on the page; focus returns to that button on close.

close()

Promise<void>

Closes the calendar.

clear()

Promise<void>

Clears the value and emits aegovDatepickerClear then aegovDatepickerChange.

getValue()

Promise<string>

Resolves the current formatted value string.

getStartDate()

Promise<string | false>

Range mode only — formatted start date, or false in single mode or with no start set.

getEndDate()

Promise<string | false>

Range mode only — formatted end date, or false in single mode or with no end set.

getPreset()

Promise<string | false>

Range mode only — the preset id matching the current selection, or false if none matches.

validate(trigger?)

Promise<AegovValidationResult>

Imperatively re-runs validation and returns the full validity state.

setCustomValidity(message)

Promise<void>

Sets a custom error message; an empty string clears it.

Pass-through attributes

AttributeNotesForwards to

aria-*

Forwarded automatically to the inner input(s).

inner <input>(s)

data-*

Forwarded automatically — useful for analytics hooks and test selectors.

inner <input>(s)

pattern, minlength, maxlength, step, autocomplete, inputmode, list, multiple, accept, capture, spellcheck, enterkeyhint, title, tabindex, form

Forwarded as-is to the inner input(s).

inner <input>(s)

autofocus

Forwarded as-is to the inner input(s), including the bare boolean-attribute shorthand (<aegov-datepicker autofocus>).

inner <input>(s)

class, style

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

host

Notes

The following notes are applicable of this component.

Built-in accessibility

  • The trigger has role="combobox", aria-haspopup="dialog", aria-expanded, and aria-controls (pointing at the dialog when open), so screen readers announce the calendar relationship.
  • The portal calendar renders as role="dialog" with aria-modal="true", labelled via aria-labelledby pointing at a visually-hidden element showing the current month and year — it updates as the user navigates months.
  • A polite aria-live region inside the portal announces month changes and range-limit messages (the focused day itself is read from its button, so it is not repeated). A second live region on the host (outside the portal) announces the final confirmed selection after the calendar closes, so the announcement survives the portal being torn down.
  • The calendar grid has role="grid"; each day is a role="gridcell" containing a button with a full-date aria-label (e.g. "Tuesday, September 8, 2026"). Unavailable dates append ", unavailable" to their label.
  • Day buttons expose aria-selected on their gridcell, aria-current="date" for today, and aria-disabled for blackout / out-of-range dates. Unavailable days stay focusable (no native disabled), so arrow-key navigation never strands focus, but they cannot be chosen.
  • Navigation chevron icons are aria-hidden="true" — the prev/next buttons carry their own bilingual aria-label ("Previous month, May 2026" style), not the icon.
  • Preset buttons expose aria-pressed to reflect whether they match the current selection. The presets sidebar has role="group" with its own aria-label.
  • Focus moves into the calendar on open (the selected day, the range start, or today) and returns on close to the element that was focused before opening (else the field), using roving tabindex within the grid so only one day is ever in the tab order at a time.
  • The trigger's inner input is readOnly — users cannot type free-form text and produce an invalid date; every selection happens through the dialog.
  • The calendar closes automatically if its trigger scrolls out of the viewport, and re-positions on every scroll and resize.

Developer responsibilities

  • Always give the datepicker a visible label: put it in aegov-form-field with an aegov-label. The label becomes the field's accessible name (in range mode it is combined with label-range-start / label-range-end, e.g. "Leave dates, Leave start"). A placeholder or the range labels alone are not enough: they are hidden once a date is chosen, so the field's purpose is no longer visible (WCAG 3.3.2). Use aria-label on the host only when a visible label is truly not possible, such as a custom icon trigger.
  • blackout only accepts an explicit, literal list of ISO dates — there is no recurring-exclusion syntax (no "every weekend", no "every Friday"). A recurring closure schedule must be enumerated into individual dates by your own code before being passed in.
  • In range mode, a second click that would violate min-range / max-range is refused: the start date stays, and a message such as "Range must be at least 3 days" shows under the months and is announced. State the allowed range in hint as well, so users know it before they open the calendar.
  • If you supply a custom trigger via the trigger slot, make sure it is itself a focusable, named element — the component does not add tab-stop behaviour to arbitrary slotted content. is-disabled stops clicks but not Enter / Space on a focusable custom trigger, so disable the trigger element as well.
  • In Arabic contexts, set dir="rtl" (and lang="ar") on the host or an ancestor for the right-to-left layout — the built-in text, month and day names then follow the page language without locale; set locale="ar" only to force Arabic regardless of the page (locale does not change direction). Set start-day="6" to match the UAE week convention.

Keyboard support

Key Function
Enter, Space Opens the calendar from the trigger; picks the focused day inside the calendar.
Arrow Left / Right Moves the focused day by one column (mirrors direction in RTL).
Arrow Up / Down Moves the focused day by one week.
Page Up / Down Moves the focused day by one month.
Shift + Page Up / Down Moves the focused day by one year.
Home / End Moves to the first / last day of the current week.
Escape Closes the calendar without committing (discards pending state in confirmation mode).
Tab Cycles only through the calendar's own focusable elements while open (a focus trap).