Basic Datepicker
The simplest usage — just drop in the element with zero configuration.
Use the global switcher above to change all examples to any calendar system.
<!-- Zero config -->
<intl-datepicker></intl-datepicker>
<!-- With options -->
<intl-datepicker
placeholder="Pick a date..."
show-alternate
calendar="persian"
locale="fa-IR">
</intl-datepicker>External Input
Target an existing input using the for attribute.
<input type="text" id="myInput" placeholder="Click to pick">
<intl-datepicker for="myInput"></intl-datepicker>Form Integration
Works as a native form element with name, required, validation, submit and reset.
<form id="booking-form">
<intl-datepicker name="appointment" required
placeholder="Select appointment date...">
</intl-datepicker>
<button type="submit">Book</button>
<button type="reset">Reset</button>
</form>form.addEventListener('submit', (e) => {
e.preventDefault();
const data = new FormData(form);
console.log([...data.entries()]);
});Date Range Selection
Click once to set start, click again to set end.
<intl-datepicker type="range"
placeholder="Select date range...">
</intl-datepicker>Range Rules
Length limits in nights, and ranges that can't cross disabled days. With
exclude-disabled="nights" check-out may land on the first booked day
(someone else checks in); days past it are blocked once check-in is picked.
<!-- Hotel: booked nights from the availability feed -->
<intl-datepicker type="range" months="2" disable-past
min-nights="2" max-nights="28" exclude-disabled="nights"
disabled-dates='["2026-10-20/2026-10-22","2026-11-03"]'>
</intl-datepicker>
<!-- Leave request: may span weekends and holidays, can't start or end on one -->
<intl-datepicker type="range" disable-weekends
disabled-dates='["2026-12-24/2026-12-26"]'>
</intl-datepicker>Hotel booking (booked nights struck through)
Leave request (weekends and holidays disabled)
Multiple Date Selection
Select multiple dates by clicking. Click again to deselect.
<intl-datepicker type="multiple"
max-dates="5" sort-dates
placeholder="Pick multiple dates...">
</intl-datepicker>Week Picker
Click any day to select the entire week.
<intl-datepicker type="week"
placeholder="Select a week...">
</intl-datepicker>Month & Year Picker
Select just a month or just a year. Gregorian values are YYYY-MM / YYYY.
In other calendars a month doesn't line up with a Gregorian one, so the value follows
Temporal.PlainYearMonth: the ISO date of the period's first day plus a calendar tag,
e.g. 2024-07-22[u-ca=persian]. The event also gives the native numbers and the Gregorian start/end.
<intl-datepicker type="month"
placeholder="Select month...">
</intl-datepicker>
<intl-datepicker type="year"
placeholder="Select year...">
</intl-datepicker>Range Presets
Predefined date ranges for quick selection.
<intl-datepicker type="range" inline
presets='[
{"label":"Today","value":"today/today"},
{"label":"Last 7 days","value":"-6d/today"},
{"label":"This month","value":"monthStart/monthEnd"},
{"label":"Last month","value":"prevMonthStart/prevMonthEnd"},
{"label":"This year","value":"yearStart/yearEnd"}
]'>
</intl-datepicker>Inline Calendar with Min/Max
Always-visible calendar with date range constraints.
<intl-datepicker inline
min="2024-01-01"
max="2025-12-31">
</intl-datepicker>Multi-Month View
Show 2 or 3 months side by side — great for range selection.
<intl-datepicker type="range"
months="2" inline>
</intl-datepicker>Display Options
Toggle week numbers, outside-day visibility, and animations.
<intl-datepicker inline
show-week-numbers
hide-outside-days
no-animation>
</intl-datepicker>First Day of Week
Override the locale's first day. The weekday header, grid, Home/End, week picker and week numbers all follow it. Try it with the Persian locale in the bar above.
<intl-datepicker type="week" first-day-of-week="mon" show-week-numbers>
</intl-datepicker>Numerals Override
Decouple the numeral system from the locale. Use Persian calendar with Latin digits, or Gregorian calendar with Arabic-Indic numerals.
<intl-datepicker locale="fa-IR" calendar="persian" numerals="latn"></intl-datepicker>
<intl-datepicker locale="en-US" calendar="gregory" numerals="arab"></intl-datepicker>Persian + Latin digits
English + Arabic-Indic digits
Caption Layout (Dropdowns)
Replace the header title button with month and/or year dropdown selects for quick navigation to distant dates.
<intl-datepicker caption-layout="dropdown"></intl-datepicker>
<intl-datepicker caption-layout="dropdown-months"></intl-datepicker>
<intl-datepicker caption-layout="dropdown-years"></intl-datepicker>dropdown
dropdown-months
dropdown-years
Persian + dropdown + min/max
Fixed Weeks (6 Rows)
Always render 6 rows of days for consistent calendar height, regardless of the month.
<intl-datepicker fixed-weeks inline></intl-datepicker>
<intl-datepicker fixed-weeks hide-outside-days inline></intl-datepicker>Fixed weeks
Fixed weeks + hide outside days
Custom Theming
Override CSS custom properties for a custom look.
<intl-datepicker inline style="
--idp-primary: #8b5cf6;
--idp-radius: 16px;
--idp-selected-bg: #8b5cf6;
--idp-today-border: #8b5cf6;">
</intl-datepicker>Disabled Dates
Disable specific dates, weekends, or use a custom filter function.
<!-- Dates and inclusive ranges -->
<intl-datepicker
disabled-dates='["2024-12-25","2024-12-31/2025-01-01"]'>
</intl-datepicker>
<!-- Closed Fridays, no past days -->
<intl-datepicker disabled-days-of-week="fri" disable-past>
</intl-datepicker>
<!-- Weekends -->
<intl-datepicker disable-weekends>
</intl-datepicker>// Custom filter: disable even days
picker.disabledDatesFilter = ({ day }) => day % 2 === 0;Static list (Dec 25, Dec 31)
Weekends disabled
Custom filter (even days disabled)
Clinic (closed Fridays, Dec 20 – Jan 5, no past days)
Custom Day Rendering
Use mapDays to add prices, colors, or badges to individual days.
picker.mapDays = ({ date, isToday }) => {
const prices = { 1: '$89', 10: '$65', 15: '$99', 25: '$150' };
const result = {};
if (prices[date.day]) {
result.content = `<span style="font-size:9px;color:#059669">
${prices[date.day]}</span>`;
}
if (date.dayOfWeek === 0 || date.dayOfWeek === 6) {
result.style = 'color:#ef4444';
}
return result;
};Allow Direct Input
Type a date in the locale's order. A hint shows the expected format, native digits
(۱۴۰۳/۰۵/۱۲) and compact entry without separators (06172024) work, and anything
unreadable gets a persistent error and marks the form field invalid. Press Enter or leave the field to commit.
<intl-datepicker allow-input
placeholder="Type a date...">
</intl-datepicker>Popup in a Dialog
The calendar opens in the browser's top layer (Popover API), so a modal <dialog>,
overflow: hidden, a transformed parent or a z-index stack can't clip or misplace it.
<dialog style="overflow: hidden">
<div style="transform: scale(1)">
<intl-datepicker></intl-datepicker>
</div>
</dialog>States: Pre-populated, Disabled & Readonly
Datepickers with pre-set values, disabled state, and readonly state.
<intl-datepicker value="2024-06-15"></intl-datepicker>
<intl-datepicker disabled value="2024-01-01"></intl-datepicker>
<intl-datepicker readonly value="2024-03-20"></intl-datepicker>Pre-populated
Disabled
Readonly
Interactive toggle: