Documentation

RollDate API

Getting started, options, methods, events, and FAQ.

Tip

weekDaysNames must be Sunday-first (['Sun','Mon',…]). When startWeekFromMonday is true, RollDate rotates the header automatically.

const picker = new RollDate(selector, options);

Constructor

Create a picker by pointing RollDate at a target element and passing an optional configuration object.

Example

new RollDate('#date');
new RollDate(['#start', '#end'], { selectType: 'range' });

Argument	Type	Required	Description
`selector`	string	yes	CSS selector for one `input` or inline container (`div`, `span`, `section`).
`selector`	[string, string]	yes	Two inputs for range mode: start field and end field.
`options`	object	no	Configuration object (see tables below).

Options

All options are optional. Defaults shown below.

Option	Type	Default	Allowed / notes	Description
`theme`	string	`'dark'`	`'dark'`, `'light'`	Visual theme of the picker.
`selectType`	string	`'single'`	`'single'`, `'range'`, `'multi'`	Selection mode. Range can use one input (`date - date`) or two inputs.
`startDate`	Date \| string	today	Any valid date in `dateFormat`	Initial calendar position and default value.
`minDate`	Date \| string	today − 100 years	≤ `maxDate`	Earliest selectable date.
`maxDate`	Date \| string	today + 100 years	≥ `minDate`	Latest selectable date.
`dateFormat`	string	from browser locale	e.g. `'YYYY-MM-DD'`, `'DD.MM.YYYY'`	Parse/format pattern for input values. Auto-detected from `locale` / `navigator.language` when omitted.
`locale`	string	browser locale	e.g. `'en-US'`, `'uk-UA'`	Hint for default `dateFormat` when not set explicitly.
`startWeekFromMonday`	boolean	`true`	`true` = Mon…Sun, `false` = Sun…Sat	First day of the week in the header.
`disabledDates`	array	`[]`	`Date[]` or `string[]` (`YYYY-MM-DD` or `dateFormat`)	Dates that cannot be selected. Strings follow `dateFormat` / locale; ISO `YYYY-MM-DD` always works.
`closeOnSelect`	boolean	`true`	—	Close popup after selection (mainly `single` mode).
`triggerSelector`	string	—	CSS selector	External element that opens the popup (with input or two inputs).
`monthsNames`	string[]	English full names	12 items	Month names in the header.
`monthsShortNames`	string[]	English short names	12 items	Labels in month view.
`weekDaysNames`	string[]	Sun…Sat	7 items	Weekday column headers.
`enableTime`	boolean	`false`	—	Show scrollable time picker in the footer.
`timeStep`	number	`1`	1–59, divides hour	Minute step (e.g. `5` → 00, 05, 10…).
`hapticFeedback`	boolean	`true`	—	Tick feedback when month/year/decade or time values change (vibration when supported, soft click otherwise).
`use12Hour`	boolean	`false`	—	12-hour clock with AM/PM column.
`footerButtons`	array	`[]`	see below	Custom footer buttons.

footerButtons item

Each entry in the footerButtons array is an object with these fields.

Field	Type	Required	Values	Description
`text`	string	yes	—	Button label.
`action`	string	no	`'today'`, `'clear'`	Built-in action (mutually exclusive with `onClick` in practice).
`onClick`	function	no	`(picker) => void`	Custom handler; receives the RollDate instance.

Callbacks

Hook into selection and lifecycle events. All default to a no-op except selectDate.

Callback	Default	Arguments / payload	When fired
`selectDate`	console.log	SINGLE`Date \| null` RANGE`Date[]` (0–2 items) MULTI`Date[]`	After the selection changes.
`onOpen`	noop	`{ period, selectedDates }`	Popup opened.
`onClose`	noop	`{ period, selectedDates }`	Popup closed.
`onViewChange`	noop	`{ from, to, current: { year, month, decade } }`	Switching day / month / year view.
`onHoverDate`	noop	`(date, meta)` — date is `Date \| null`	Hovering a day (or leaving the calendar).

Methods & properties

Call these on the instance returned by the constructor.

Name	Signature	Returns	Description
`open()`	()	`void`	Open popup (popup mode).
`close()`	()	`void`	Close popup.
`selectToday()`	()	`void`	Select today; applies current time if `enableTime`.
`clearSelection()`	()	`void`	Clear all selected dates.
`setDisabledDates(dates)`	((Date\|string)[])	`void`	Replace the full disabled-dates list.
`disableDate(date)`	(Date\|string)	`void`	Disable one date.
`enableDate(date)`	(Date\|string)	`void`	Re-enable one date.
`isDateDisabled(date)`	(Date\|string)	`boolean`	Check if a date is disabled.
`destroy()`	()	`void`	Remove DOM nodes and detach listeners.
`selectedDates`	getter	`Date[]`	Currently selected dates (read-only).
`period`	getter	`'day'` \| `'month'` \| `'year'`	Active calendar view.

Display modes

RollDate picks its mode from the type of the target element.

Mode	Trigger	Behaviour
Popup	`input` or `triggerSelector`	Calendar is appended to `document.body`, shown on focus/click.
Inline	`div`, `span`, `section`	Calendar is rendered inside the element, always visible.

Examples

A live inline instance. More interactive demos live on the homepage playground.

Note

Popup vs inline is chosen by the element type: input → popup, div/section → inline.

new RollDate('#docs-demo', {…})

Recipes

Copy-paste patterns for common integrations. Live previews where noted.

Date range (one input)

Single field with start and end in one value — ideal for filters and travel forms.

Code

new RollDate('#trip', {
  selectType: 'range',
  closeOnSelect: false
});

Date range (two inputs)

Separate start and end fields. Pass an array of two selectors — RollDate wires both inputs.

Code

new RollDate(['#check-in', '#check-out'], {
  selectType: 'range'
});

Date & time

Keep the popup open until the user confirms time. Use closeOnSelect: false when time is enabled.

enableTime: true

Code

new RollDate('#appointment', {
  enableTime: true,
  timeStep: 15,
  use12Hour: false,
  closeOnSelect: false
});

Booking window

Limit selectable dates with minDate / maxDate and block specific days.

minDate + disabledDates

Code

const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);

new RollDate('#booking', {
  minDate: new Date(),
  maxDate: new Date(Date.now() + 90 * 864e5),
  disabledDates: [tomorrow]
  // strings work too: ['2026-07-22'] or ['22.07.2026'] with dateFormat
});

Localization

Override month and weekday labels. weekDaysNames stays Sunday-first; set startWeekFromMonday to rotate the header.

locale: 'de-DE'

Code

new RollDate('#date-de', {
  locale: 'de-DE',
  startWeekFromMonday: true,
  monthsNames: ['Januar', 'Februar', /* … */],
  monthsShortNames: ['Jan', 'Feb', /* … */],
  weekDaysNames: ['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa']
});

Readonly input + external trigger

Prevent keyboard entry on mobile; open the picker from a button or icon.

HTML

<input id="date" type="text" readonly placeholder="Pick a date" />
<button type="button" id="open-date">Open</button>

Code

new RollDate('#date', {
  triggerSelector: '#open-date'
});

Custom footer buttons

Built-in action: 'today' or your own handler via onClick.

Code

new RollDate('#date', {
  closeOnSelect: false,
  footerButtons: [
    { text: 'Today', action: 'today' },
    {
      text: 'Apply',
      onClick: function (picker) {
        picker.close();
      }
    }
  ]
});

FAQ

Can I use it with React / Vue / Svelte?

Yes. RollDate is plain JavaScript. Mount it in useEffect / onMounted (or equivalent) and call destroy() on unmount. No official framework wrapper is required.

Does it require Moment.js or Day.js?

No. Zero runtime dependencies — only the browser Date object.

How do I clean up an instance?

Call picker.destroy() before removing the host element from the DOM, or when your SPA route unmounts. This detaches listeners and removes injected popup nodes.

Can I attach multiple pickers on one page?

Yes. Create one RollDate instance per input or container. Each instance is independent — store references if you need to call methods later.

Should the input be readonly?

For popup mode on mobile, readonly is recommended so the native keyboard does not cover the calendar. Desktop users can still open the picker on focus/click.

Can I disable weekends or specific days?

Yes. Pass disabledDates, or use disableDate / setDisabledDates at runtime. There is no built-in “weekends only” flag — build a list or use disableDate in a loop. Combine with minDate / maxDate for booking windows.

Can I localize months and weekdays?

Yes. Override monthsNames, monthsShortNames, weekDaysNames, and optionally locale / dateFormat.

Popup or inline?

Attach to an input for popup. Pass a container element (div, section, …) for inline. Use triggerSelector for an external open button.

Is there TypeScript support?

Yes. @rolldate/core ships with rolldate.d.ts — options, methods, and callbacks are typed out of the box.