or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core.mdindex.mdinstance.mdlocalization.mdoptions.mdplugins.md
tile.json

plugins.mddocs/

Plugin System

Extensible plugin architecture for adding specialized functionality to flatpickr instances.

Plugin Architecture

Plugin Type

type Plugin<E = {}> = (fp: Instance & E) => Options;

A plugin is a function that receives a flatpickr instance and returns configuration options to modify behavior.

Using Plugins

import rangePlugin from "flatpickr/dist/plugins/rangePlugin";

flatpickr("#date", {
  mode: "range",
  plugins: [
    rangePlugin({ input: "#end-date" })
  ]
});

Built-in Plugins

rangePlugin

Enhanced range selection with separate input fields for start and end dates.

import rangePlugin from "flatpickr/dist/plugins/rangePlugin";

interface RangeConfig {
  input?: string | HTMLInputElement;
  position?: "left";
}

rangePlugin(config?: RangeConfig): Plugin;

Configuration:

  • input: Selector or element for end date input
  • position: Position of the end input ("left" places it before start input)
// HTML: <input id="start"> <input id="end">
flatpickr("#start", {
  mode: "range",
  plugins: [
    rangePlugin({ input: "#end" })
  ]
});

// Both inputs will be synchronized
// Start input shows: "2023-12-01 to 2023-12-07"  
// End input shows: "2023-12-07"

minMaxTimePlugin

Time constraints for different dates, allowing different time ranges per day.

import minMaxTimePlugin from "flatpickr/dist/plugins/minMaxTimePlugin";

interface TimeLimit {
  minTime?: string;
  maxTime?: string;
}

interface MinMaxTimeConfig {
  table?: { [date: string]: TimeLimit };
  getTimeLimits?: (date: Date) => TimeLimit;
}

minMaxTimePlugin(config: MinMaxTimeConfig): Plugin;

Configuration:

  • table: Object mapping date strings to time limits
  • getTimeLimits: Function returning time limits for a date
flatpickr("#appointment", {
  enableTime: true,
  plugins: [
    minMaxTimePlugin({
      table: {
        "2023-12-25": { minTime: "09:00", maxTime: "17:00" },
        "2023-12-26": { minTime: "10:00", maxTime: "14:00" }
      }
    })
  ]
});

// Dynamic time limits
flatpickr("#dynamic-time", {
  enableTime: true,
  plugins: [
    minMaxTimePlugin({
      getTimeLimits: (date) => {
        const isWeekend = date.getDay() === 0 || date.getDay() === 6;
        return isWeekend
          ? { minTime: "10:00", maxTime: "18:00" }
          : { minTime: "08:00", maxTime: "20:00" };
      }
    })
  ]
});

momentPlugin

Integration with Moment.js for advanced date parsing and formatting.

import momentPlugin from "flatpickr/dist/plugins/momentPlugin";

momentPlugin(): Plugin;

Requires Moment.js to be loaded globally.

// Requires: <script src="moment.js"></script> or import moment
flatpickr("#moment-date", {
  plugins: [momentPlugin()],
  dateFormat: "YYYY-MM-DD",
  // Can now use Moment.js format tokens
});

scrollPlugin

Mouse wheel and scroll support for incrementing/decrementing dates and times.

import scrollPlugin from "flatpickr/dist/plugins/scrollPlugin";

interface ScrollConfig {
  yearIncrement?: number;
  monthIncrement?: number;
  dayIncrement?: number;
  hourIncrement?: number;
  minuteIncrement?: number;
}

scrollPlugin(config?: ScrollConfig): Plugin;

Configuration:

  • yearIncrement: Years to increment per scroll (default: 1)
  • monthIncrement: Months to increment per scroll (default: 1)
  • dayIncrement: Days to increment per scroll (default: 1)
  • hourIncrement: Hours to increment per scroll (default: 1)
  • minuteIncrement: Minutes to increment per scroll (default: 5)
flatpickr("#scroll-date", {
  enableTime: true,
  plugins: [
    scrollPlugin({
      dayIncrement: 7,      // Scroll by weeks
      hourIncrement: 2,     // Scroll hours by 2
      minuteIncrement: 15   // Scroll minutes by 15
    })
  ]
});

confirmDate

Adds a confirmation step before finalizing date selection with a customizable confirm button.

import confirmDate from "flatpickr/dist/plugins/confirmDate/confirmDate";

interface Config {
  confirmIcon?: string;
  confirmText?: string;
  showAlways?: boolean;
  theme?: string;
}

confirmDate(config?: Config): Plugin;

Configuration:

  • confirmIcon: HTML for confirm button icon (default: SVG checkmark)
  • confirmText: Text for confirm button (default: "OK ")
  • showAlways: Always show confirm button (default: false)
  • theme: Color theme for confirm button (default: "light")
flatpickr("#confirm-date", {
  plugins: [
    confirmDate({
      confirmText: "Confirm",
      theme: "dark",
      showAlways: true
    })
  ]
});

labelPlugin

Ensures proper label associations for accessibility by transferring IDs to the visible input element.

import labelPlugin from "flatpickr/dist/plugins/labelPlugin/labelPlugin";

labelPlugin(): Plugin;

This plugin automatically handles ID transfer when using altInput or mobileInput, ensuring screen readers can properly associate labels with the visible input.

// HTML: <label for="date-input">Select Date:</label><input id="date-input">
flatpickr("#date-input", {
  altInput: true,
  plugins: [labelPlugin()]
});
// The plugin ensures the altInput receives the ID for proper label association

monthSelect

Provides a month/year only picker with dropdown interface instead of full calendar.

import monthSelect from "flatpickr/dist/plugins/monthSelect";

interface Config {
  shorthand?: boolean;
  dateFormat?: string;
  altFormat?: string;
  theme?: string;
}

monthSelect(config?: Partial<Config>): Plugin;

Configuration:

  • shorthand: Use abbreviated month names (default: false)
  • dateFormat: Date format for the picker (default: "F Y")
  • altFormat: Alt format for display (default: "F Y")
  • theme: Color theme (default: "light")
flatpickr("#month-picker", {
  plugins: [
    monthSelect({
      shorthand: true,
      dateFormat: "M Y",
      altFormat: "F Y"
    })
  ]
});

weekSelect

Enables week-based selection where clicking any day selects the entire week.

import weekSelect from "flatpickr/dist/plugins/weekSelect/weekSelect";

weekSelect(): Plugin;

This plugin automatically configures the picker for single mode and applies week formatting. The selected week is highlighted and the date format shows week information.

flatpickr("#week-picker", {
  plugins: [weekSelect()]
});
// Default format: "Week #W, Y" (e.g., "Week #25, 2023")
// Automatically sets mode to "single" and disables time

Creating Custom Plugins

Basic Plugin Structure

function customPlugin(config = {}) {
  return function(fp) {
    // Plugin initialization
    
    // Return configuration overrides
    return {
      // Override/add configuration options
      onReady: [
        function() {
          // Plugin setup after flatpickr is ready
        }
      ],
      
      onChange: [
        function(selectedDates, dateStr) {
          // Handle date changes
        }
      ],
      
      onOpen: [
        function() {
          // Handle calendar open
        }
      ]
    };
  };
}

// Usage
flatpickr("#custom", {
  plugins: [customPlugin({ option: "value" })]
});

Plugin with DOM Manipulation

function highlightWeekendsPlugin() {
  return function(fp) {
    return {
      onDayCreate: [
        function(dObj, dStr, fp, dayElem) {
          const date = dayElem.dateObj;
          if (date.getDay() === 0 || date.getDay() === 6) {
            dayElem.classList.add("weekend-highlight");
          }
        }
      ]
    };
  };
}

// CSS: .weekend-highlight { background: #ffe6e6; }
flatpickr("#weekends", {
  plugins: [highlightWeekendsPlugin()]
});

Plugin with External Integration

function apiSyncPlugin(apiEndpoint) {
  return function(fp) {
    return {
      onChange: [
        function(selectedDates, dateStr) {
          // Sync selection with API
          fetch(apiEndpoint, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ 
              dates: selectedDates.map(d => d.toISOString()) 
            })
          });
        }
      ]
    };
  };
}

flatpickr("#api-sync", {
  plugins: [apiSyncPlugin("/api/dates")]
});

Plugin Loading

ES Modules

import rangePlugin from "flatpickr/dist/plugins/rangePlugin";
import confirmDate from "flatpickr/dist/plugins/confirmDate/confirmDate";

CommonJS

const rangePlugin = require("flatpickr/dist/plugins/rangePlugin");

Browser/CDN

<script src="https://cdn.jsdelivr.net/npm/flatpickr"></script>
<script src="https://cdn.jsdelivr.net/npm/flatpickr/dist/plugins/rangePlugin.js"></script>

<script>
flatpickr("#date", {
  plugins: [rangePlugin()]
});
</script>

Plugin CSS

Many plugins require additional CSS files:

<!-- Range Plugin CSS -->
<link rel="stylesheet" href="flatpickr/dist/plugins/rangePlugin.css">

<!-- Confirm Date Plugin CSS -->
<link rel="stylesheet" href="flatpickr/dist/plugins/confirmDate/confirmDate.css">

<!-- Month Select Plugin CSS -->  
<link rel="stylesheet" href="flatpickr/dist/plugins/monthSelect/style.css">

Multiple Plugins

import rangePlugin from "flatpickr/dist/plugins/rangePlugin";
import confirmDate from "flatpickr/dist/plugins/confirmDate/confirmDate";
import scrollPlugin from "flatpickr/dist/plugins/scrollPlugin";

flatpickr("#multi-plugin", {
  mode: "range",
  plugins: [
    rangePlugin({ input: "#end-date" }),
    confirmDate({ confirmText: "Apply Range" }),
    scrollPlugin({ dayIncrement: 7 })
  ]
});