Getting started

System

Components

Extra

Datepicker

Calendar interface for selecting dates.

Open in Figma

The Datepicker component provides an intuitive calendar interface for selecting dates. It is built on top of Air Datepicker, a powerful and flexible date picker library.

The component wraps a standard text input and enhances it with a calendar popup that supports single date selection, date ranges, custom formats, and localization.

Installation

CDN (Quick Start)

Include the CSS and JavaScript via CDN:

<link href="https://cdn.jsdelivr.net/npm/air-datepicker/air-datepicker.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/air-datepicker/air-datepicker.min.js"></script>

npm

Install via npm for a bundled workflow:

npm i air-datepicker -S

Usage

CDN Usage

Create an input and initialize the datepicker after the page loads:

<input type="text" id="myDatepicker" placeholder="Select a date">

<script>
// Wait for the page to fully load
document.addEventListener('DOMContentLoaded', function() {
  new AirDatepicker('#myDatepicker');
});
</script>

npm Usage

Import the library and initialize it in your JavaScript module:

import AirDatepicker from 'air-datepicker';
import 'air-datepicker/air-datepicker.css';

new AirDatepicker('#my-element', options);

Options

Air Datepicker supports a wide range of configuration options. Here are the most commonly used ones:

{
  // Locale settings
  locale: {
    digits: [],        // Custom digits for number display
    days: [],          // Full day names
    daysShort: [],     // Short day names
    daysMin: [],       // Minimal day names
    months: [],        // Full month names
    monthsShort: [],   // Short month names
    today: "Today",
    clear: "Clear",
    dateFormat: "dd.mm.yyyy",
    timeFormat: "HH:MM",
    firstDay: 0        // First day of the week (0 = Sunday)
  },

  // Date format
  dateFormat: "dd.mm.yyyy",
  altField: null,      // Field to store alternative date format
  altFieldDateFormat: "T",

  // Selection mode
  multipleDates: false,     // Allow multiple date selection
  range: false,             // Enable range selection
  toggleSelected: true,     // Allow deselecting by clicking again

  // Navigation
  navTitles: {
    days: "MMMM, yyyy",
    months: "yyyy",
    years: "yyyy – yyyy"
  },

  // View options
  startView: "days",  // Initial view: 'days', 'months', 'years'
  minView: "days",    // Minimum view available
  visibleDays: 7,     // Days visible in the calendar

  // Time picker
  timepicker: false,
  onlyTimepicker: false,
  hours: [0, 23],
  minutes: [0, 59],
  timeFormat: "HH:MM",

  // Positioning
  position: "top left",  // Popup position relative to input
  offset: 12,            // Distance between input and popup

  // Styling
  classes: "",           // Additional CSS classes
  inline: false,         // Render inline (not as popup)

  // Buttons
  buttons: [],           // Array of custom buttons
  todayButton: false,    // Show "Today" button
  clearButton: false,    // Show "Clear" button

  // Restrictions
  minDate: false,
  maxDate: false,
  disableNavWhenOutOfRange: true,

  // Selection handler
  onSelect: ({ date, formattedDate, datepicker }) => {},
  onChangeView: ({ view }) => {},
  onRender: (date) => {}
}

For the complete list of options and advanced usage, refer to the Air Datepicker documentation.

Common Examples

Single date with time:

new AirDatepicker('#myDatepicker', {
  timepicker: true,
  dateFormat: "dd.mm.yyyy HH:MM"
});

Multiple date selection:

new AirDatepicker('#myDatepicker', {
  multipleDates: true,
  multipleDatesSeparator: ", "
});

Date range selection:

new AirDatepicker('#myDatepicker', {
  range: true,
  multipleDatesSeparator: " - "
});

Methods

After initialization, you can control the datepicker using its instance methods:

const dp = new AirDatepicker('#myDatepicker');

// Select a date
dp.selectDate(new Date());

// Clear selection
dp.clear();

// Show the calendar
dp.show();

// Hide the calendar
dp.hide();

// Destroy the datepicker instance
dp.destroy();

// Get selected dates
dp.selectedDates;  // Returns array of Date objects

// Update options dynamically
dp.update({ dateFormat: "yyyy-mm-dd" });

Event Handlers

Use event callbacks to respond to user actions:

  • onSelect – Called when a date is selected
  • onChangeView – Called when the view changes (days/months/years)
  • onRender – Called when a date cell is rendered (for custom HTML)

For the complete list of options and advanced usage, refer to the Air Datepicker documentation.

On this page