@preline/datepicker

Advanced Datepicker

Create visually appealing and interactive datepickers in combination with the Datepicker JavaScript plugin.

Contents

• Overview
• Installation
• Basic usage
• Configuration Options
• JavaScript API
• Events
• Common Patterns
• License

Overview

The Advanced Datepicker component provides a comprehensive date selection interface with support for custom templates, multiple date formats, time selection, and integration with Vanilla Calendar Pro. It offers flexible configuration options for styling and behavior.

Key Features:

• Date and time selection
• Custom select inputs for months, years, and time
• Multiple date formats and locales
• Custom templates for arrows and time display
• Integration with Vanilla Calendar Pro
• Programmatic control via JavaScript API
• Utility classes support

Installation

To get started, install Datepicker plugin via npm, else you can skip this step if you are already using Preline UI as a package.

npm i @preline/select @preline/datepicker

CSS

Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

Use styles.css with theme.css for the default themed appearance:

@import "tailwindcss";

/* @preline/select */
@source "../node_modules/@preline/select/*.js";
@import "./node_modules/@preline/select/variants.css";

/* @preline/datepicker */
@source "../node_modules/@preline/datepicker/*.js";
@import "./node_modules/@preline/datepicker/variants.css";
@import "./node_modules/@preline/datepicker/styles.css";
@import "./node_modules/@preline/datepicker/theme.css";

Use styles-utility.css instead when you plan to style the datepicker entirely with Tailwind utility classes. In this case theme.css is not needed:

@import "tailwindcss";

/* @preline/select */
@source "../node_modules/@preline/select/*.js";
@import "./node_modules/@preline/select/variants.css";
@import "./node_modules/@preline/select/theme.css";

/* @preline/datepicker */
@source "../node_modules/@preline/datepicker/*.js";
@import "./node_modules/@preline/datepicker/variants.css";
@import "./node_modules/@preline/datepicker/styles-utility.css";

@preline/select is required for styling the embedded select dropdowns used in custom-select mode.

JavaScript

Include the JavaScript that powers the interactive elements near the end of your </body> tag:

<script src="./node_modules/@preline/datepicker/index.js"></script>

Manual Initialization

Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

<script type="module">
  import HSDatepicker from "@preline/datepicker/non-auto.mjs";

  new HSDatepicker(document.querySelector("#datepicker"));
</script>

Via Bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module. vanilla-calendar-pro and the Advanced Select plugin are bundled inside @preline/datepicker, so no separate imports are needed.

@preline/datepicker is the auto-init entry: it scans the DOM and initializes matching elements automatically.

import "@preline/datepicker";

@preline/datepicker/non-auto is the manual entry: use it when you want explicit control over when initialization happens, either via autoInit() or by creating a specific instance yourself.

import HSDatepicker from "@preline/datepicker/non-auto";

HSDatepicker.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#datepicker");
if (el) new HSDatepicker(el);

TypeScript

This package ships with TypeScript type definitions. No additional @types/ package is needed.

Basic usage

The following example demonstrates the minimal HTML structure required for an advanced datepicker component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The datepicker appears when the input is focused.

<input
  class="hs-datepicker"
  type="text" placeholder="" 
  readonly
  data-hs-datepicker='{
    "type": "default",
    "dateMax": "2050-12-31",
    "styles": {
      "week": "vc-week",
      "weekDay": "vc-week__day",
      "dates": "vc-dates",
      "date": "vc-date",
      "arrowPrev": "vc-arrow vc-arrow_prev",
      "arrowNext": "vc-arrow vc-arrow_next"
    },
    "mode": "custom-select"
  }'>

Structure Requirements:

• hs-datepicker: Required class on the input element
• data-hs-datepicker: Required attribute containing configuration options as JSON
• readonly attribute on the input to prevent manual editing
• type="text" on the input element

Initial State:

• Input field is empty by default
• Datepicker appears when input is focused or clicked

Configuration Options

Data Options

Note: This component requires the use of the Vanilla Calendar Pro plugin. Most options available in the plugin are available in our wrapper. Check Vanilla Calendar Pro Options for more details.

Data options are specified in the data-hs-datepicker attribute as a JSON object.

Example:

<input
  class="hs-datepicker"
  type="text"
  readonly
  data-hs-datepicker='{
    "mode": "custom-select",
    "dateFormat": "YYYY-MM-DD",
    "dateLocale": "en",
    "inputModeOptions": {
      "dateSeparator": "/"
    }
  }'>

Tailwind Modifiers

JavaScript API

Note: This component requires the use of the Vanilla Calendar Pro plugin. Most methods available in the plugin are available through our wrapper. Check Vanilla Calendar Pro Methods for more details.

The HSDatepicker object is available in the global window object after the plugin is loaded. Most methods from Vanilla Calendar Pro are available through the wrapper.

Instance Methods

These methods are called on a datepicker instance.

Static Methods

These methods are called directly on the HSDatepicker class.

Usage Examples

Example 1: Getting current state

// Get the datepicker instance
const instance = HSDatepicker.getInstance('.hs-datepicker', true);

if (instance) {
  const { element } = instance;
  // Get current state
  const state = element.getCurrentState();

  console.log('Selected dates:', state.selectedDates);
  console.log('Selected time:', state.selectedTime);
}

Example 2: Formatting dates

const instance = HSDatepicker.getInstance('.hs-datepicker', true);

if (instance) {
  const { element } = instance;
  // Format a date
  const formatted = element.formatDate(new Date(), 'YYYY-MM-DD');

  console.log('Formatted date:', formatted);
}

Example 3: Destroying datepicker instance

const instance = HSDatepicker.getInstance('.hs-datepicker', true);

if (instance) {
  const { element } = instance;
  const removeBtn = document.querySelector('#hs-remove-btn');

  removeBtn.addEventListener('click', () => {
    // Clean up before removing from DOM
    element.destroy();
    // Now safe to remove the element
    document.querySelector('.hs-datepicker').remove();
  });
}

Events

Datepicker instances emit events that can be listened to for date selection lifecycle hooks.

Event Usage Example

// Get datepicker instance
const instance = HSDatepicker.getInstance('.hs-datepicker', true);

if (instance) {
  const { element } = instance;

  // Listen for date or time changes
  element.on('change', ({ selectedDates, selectedTime }) => {
    console.log('Selected dates:', selectedDates);
    console.log('Selected time:', selectedTime);
    // Update dependent fields, validate form, etc.
  });
}

Common Patterns

Pattern 1: Custom Select Mode

Use custom select inputs for months, years, and time.

<input
  class="hs-datepicker"
  type="text"
  readonly
  data-hs-datepicker='{
    "mode": "custom-select"
  }'>

Pattern 2: Custom Date Format

Set a custom date format and separator.

<input
  class="hs-datepicker"
  type="text"
  readonly
  data-hs-datepicker='{
    "dateFormat": "YYYY-MM-DD",
    "inputModeOptions": {
      "dateSeparator": "/"
    }
  }'>

License

Copyright (c) 2024 Htmlstream.

Licensed under the MIT License.