Date Picker
Calendar-based date picker with keyboard navigation.
<arc-date-picker>Overview
DatePicker provides a calendar-based date selection interface that combines a read-only text input with a dropdown calendar grid. Clicking the input toggles a 6-row calendar showing the current month with previous/next month navigation arrows. The selected date is displayed in a human-readable format (e.g. "Jan 15, 2026") inside the input, while the underlying value property stores the date as an ISO string (YYYY-MM-DD).
The calendar grid highlights today's date with an inset ring, the currently selected date with a filled accent-primary circle, and outside-month dates with reduced opacity. The min and max properties constrain the selectable range: dates outside it appear dimmed and are non-interactive. Previous and next month buttons in the calendar header allow quick navigation without changing the selected value.
When a date is selected, the component dispatches an arc-change event with the ISO date string in the detail. Clicking outside the component or pressing Escape closes the dropdown and returns focus to the input. The dropdown uses a slide-down entrance animation that respects prefers-reduced-motion. A configurable label renders above the input as an uppercase accent-font heading, consistent with other ARC UI form controls.
Guidelines
When to use
- Set min and max to constrain the date range when the context requires it (e.g. future-only booking dates)
- Provide a descriptive label like "Start Date" or "Date of Birth" for accessibility
- Use the ISO string value for form submission and API communication, not the display format
- Listen to arc-change to capture the selected date and validate it against business rules
- Set the initial value property when editing an existing record so the calendar opens to the correct month
When not to use
- Do not use DatePicker for date ranges. Use two DatePicker instances with coordinated min/max instead
- Do not allow the user to type directly into the input; it is read-only by design to ensure valid date formats
- Do not set min greater than max, as this will disable all dates and make the picker unusable
- Do not forget to handle the arc-change event. Without it, the selected date is not captured
- Do not place DatePicker inside a container with overflow: hidden, as the calendar dropdown will be clipped
Features
- Calendar dropdown with 6-row grid showing current, previous, and next month days
- ISO string value format (YYYY-MM-DD) for consistent data handling
- Human-readable date display in the input (e.g. "Jan 15, 2026")
- Min and max date constraints that disable out-of-range dates visually
- Today highlight with an inset border ring for orientation
- Previous/next month navigation arrows in the calendar header
- Escape key and outside-click dismissal with focus restoration to the input
- Animated dropdown entrance with `prefers-reduced-motion` support
Preview
Usage
This component requires JavaScript. No pure HTML/CSS version is available. Use the Web Component directly or a framework wrapper.
<arc-date-picker label="Select Date" placeholder="Choose a date"></arc-date-picker>import { DatePicker } from '@arclux/arc-ui-react';
export default function Example() {
return (
<DatePicker label="Select Date" placeholder="Choose a date" />
);
}<script setup>
import { DatePicker } from '@arclux/arc-ui-vue';
</script>
<template>
<DatePicker label="Select Date" placeholder="Choose a date" />
</template><script>
import { DatePicker } from '@arclux/arc-ui-svelte';
</script>
<DatePicker label="Select Date" placeholder="Choose a date" />import { Component } from '@angular/core';
import { DatePicker } from '@arclux/arc-ui-angular';
@Component({
imports: [DatePicker],
template: `
<arc-date-picker label="Select Date" placeholder="Choose a date"></arc-date-picker>
`,
})
export class MyComponent {}import { DatePicker } from '@arclux/arc-ui-solid';
export default function Example() {
return (
<DatePicker label="Select Date" placeholder="Choose a date" />
);
}import { DatePicker } from '@arclux/arc-ui-preact';
export default function Example() {
return (
<DatePicker label="Select Date" placeholder="Choose a date" />
);
}API
valuestring''- The selected date as an ISO string (YYYY-MM-DD). Set this to pre-select a date. Updated when the user picks a date from the calendar.
namestring''minstring''- Minimum selectable date as an ISO string. Dates before this are visually dimmed and non-interactive.
maxstring''- Maximum selectable date as an ISO string. Dates after this are visually dimmed and non-interactive.
placeholderstring'Select date'- Placeholder text displayed in the input when no date is selected.
disabledbooleanfalse- Disables the date picker, reducing opacity and preventing the calendar from opening.
labelstring''- Label text rendered above the input in uppercase accent font styling.
localestring''- BCP 47 tag used for month and weekday names. Defaults to the document's
lang, then the browser's language. first-day-of-weeknumber0- Which day the week starts on, 1 = Monday … 7 = Sunday. Defaults to the locale's own convention, so most of the world gets Monday and the US gets Sunday without configuring anything.
openbooleanfalse- Whether the calendar dropdown is visible. Reflected so it can be opened programmatically or styled from CSS. Held at
falsewhiledisabled. size'sm' | 'md' | 'lg''md'- Control size.
mdis the default;smandlgscale the field padding. formAssociatedbooleantruepropertiesobject{ // flag(), unlike `disabled`. The exclusion in props.js is specifically // about form-associated *platform* semantics: a `disabled` content // attribute that is merely present makes the element actually disabled // per the HTML spec, and formDisabledCallback assigns the property back, // so no converter can win. Neither of these is platform-mapped: // `required` is enforced by _computeValidity() below and `readonly` by // each component's own interaction handlers, so the stock converter buys // nothing here and costs the usual bug: `required="false"` read as true, // blocking submission of a form the author meant to leave optional. // Finding #48's shape, across all 26 form controls at once. required: flag(false), readonly: flag(false), }- Lit merges static properties up the prototype chain, so every consumer
gets these without declaring them.
requiredparticipates in constraint validation below;readonlyreflects for styling and is enforced by each component's interaction handlers (the mixin can't know which gestures mutate state). autoValidatesbooleantrue- Components that run their own constraint-validation logic (pattern checks, range checks) opt out of the automatic required sync by overriding this to false, and own the whole validity flag set instead.
formvalidityvalidationMessagerequiredbooleanfalsereadonlybooleanfalse
Methods
checkValidity()boolean- Whether the control currently satisfies its constraints, per the native
constraint-validation API. Fires
invalidon the element when it does not, and reports nothing to the user. reportValidity()boolean- As checkValidity(), but also shows the browser's validation message against the control when it fails.
Events
arc-changedetail:{ value: string }- Fired when a date is selected
See Also
- CalendarMonth-view calendar grid for date selection, with min/max constraints, keyboard navigation, and today highlighting.
- InputVersatile form control supporting single-line text, email, password, and multiline textarea modes with built-in label, placeholder, and validation states. Pairs with Form for complete data-entry workflows.