Flatpickr

4.6.13 · active · verified Sun Apr 19

Flatpickr is a lightweight, dependency-free JavaScript datetime picker library, currently stable at version 4.6.13. It offers a rich set of features for date and time input, including range selections, multiple date selections, time-only pickers, and highly customizable date disabling logic. The library maintains an active release cadence, frequently publishing patch versions to address bugs and introduce minor enhancements, as seen in the recent 4.6.x releases. Unlike many alternatives, Flatpickr avoids heavy dependencies like jQuery or Moment.js, contributing to smaller bundle sizes. It provides 51 locales, 8 themes, and a plugin architecture, with official and community-maintained wrappers for popular frameworks like React, Angular, and Vue. Its primary differentiator is providing extensive functionality and a polished user experience without sacrificing performance or introducing external bloat.

Common errors

```
TypeError: flatpickr is not a function
```
cause The `flatpickr` function was not imported or loaded correctly, or the script tag was placed before the element it targets.

fix Ensure you `import flatpickr from 'flatpickr';` in an ESM environment or that the `flatpickr` script is loaded before its invocation in a non-module environment. For DOM-ready initialization, wrap the `flatpickr` call in a `DOMContentLoaded` listener.
```
Flatpickr: invalid input value
```
cause An invalid date string was provided to `flatpickr` options like `defaultDate`, `minDate`, `maxDate`, or `enable/disable` when `allowInput` and `allowInvalidPreload` were enabled, causing the UI to break.

fix Verify that all date strings passed to Flatpickr options conform to a parseable format, or match the `dateFormat` if specified. Debug the input value and ensure it's a valid date. Consider using `new Date()` objects for clarity.
```
Module not found: Error: Can't resolve 'flatpickr/dist/flatpickr.min.css'
```
cause The CSS import path is incorrect or the `flatpickr` package is not correctly installed in `node_modules`.

fix Check the import path for the CSS, ensuring it points to the correct location (e.g., `flatpickr/dist/flatpickr.min.css`). Run `npm install flatpickr` or `yarn add flatpickr` to ensure the package is correctly installed. Sometimes `npm rebuild` or clearing `node_modules` and reinstalling helps.
```
Uncaught TypeError: Cannot read property 'add' of undefined at setupInputs
```
cause This error typically indicates that `flatpickr` was initialized on an element that doesn't exist in the DOM at the time of initialization, or the selector was incorrect.

fix Ensure the target HTML element for `flatpickr` (e.g., `input.my-datepicker`) is present in the DOM before `flatpickr` is called. Wrap the initialization in a `DOMContentLoaded` event listener or place the script at the end of `<body>`.

Warnings

breaking Versions prior to 4.6.11 had a bug that caused `altInput` and `altFormat` to break. Update to 4.6.11 or newer to ensure correct functionality if you rely on these options.
Fix: Update flatpickr to version 4.6.11 or later: `npm install flatpickr@latest`.
gotcha When integrating Flatpickr into a modern JavaScript framework (like React, Vue, Angular), it is highly recommended to use the dedicated wrapper components (e.g., `react-flatpickr`). Direct DOM manipulation of the `flatpickr` instance within a component's lifecycle can lead to unexpected behavior, performance issues, or conflicts with the framework's virtual DOM.
gotcha Flatpickr requires its CSS to be imported for proper styling. Forgetting to import the `flatpickr.min.css` or a specific theme CSS will result in an unstyled and potentially unusable date picker UI.
gotcha If using Flatpickr with Internet Explorer 11 or older, be aware that versions >=4.6.7 might cause syntax errors due to ES6 features in the ESM build (`dist/esm/index.js`). Ensure your build process transpiles `node_modules` for IE11 compatibility, or explicitly load the UMD build.
gotcha When reinitializing Flatpickr on an element that has been moved in the DOM, issues like duplicate input fields or non-functional pickers can occur. This is because Flatpickr binds to properties on the original element, which might not be preserved or correctly updated after DOM manipulation. Ensure to destroy previous instances before reinitializing or use specific framework wrappers designed to handle such scenarios.
gotcha In some older browsers, particularly IE11, Flatpickr can fail to initialize if an input field with a `placeholder` attribute is used, as it might incorrectly interpret the placeholder text as an initial value, leading to an error.

Install

npm install flatpickr npm
yarn add flatpickr yarn
pnpm add flatpickr pnpm

Imports

flatpickr
wrong:
```
const flatpickr = require('flatpickr');
```
correct:
```
import flatpickr from 'flatpickr';
```
ESM imports are recommended, especially for TypeScript. CommonJS `require` is supported but can lead to issues with modern bundlers and some tools.
flatpickr CSS
wrong:
```
import 'flatpickr/flatpickr.min.css';
```
correct:
```
import 'flatpickr/dist/flatpickr.min.css';
```
Always import the CSS for styling. You can also import specific themes like `flatpickr/dist/themes/material_green.css` instead.
Locale
wrong:
```
import { de } from 'flatpickr/dist/l10n/de.js';
```
correct:
```
import { German } from 'flatpickr/dist/l10n/de';
```
Locales are named exports (e.g., `German` for `de.js`) from files within the `l10n` directory. After importing, pass the locale object in the configuration: `{ locale: German }`.
Plugin
```
import monthSelectPlugin from 'flatpickr/dist/plugins/monthSelect/monthSelect';
```
Plugins are default exports from their respective files within `dist/plugins`. They are initialized by passing an instance of the plugin to the `plugins` array in the flatpickr configuration: `{ plugins: [new monthSelectPlugin({})] }`.

Quickstart

This quickstart demonstrates how to initialize two Flatpickr instances: a datetime picker with a French locale and a date range picker. It dynamically creates input elements, imports necessary CSS and locale, and configures each instance with common options like `enableTime`, `dateFormat`, `altInput` for user-friendly display, and event hooks.

import flatpickr from 'flatpickr';
import 'flatpickr/dist/flatpickr.min.css';
import { French } from 'flatpickr/dist/l10n/fr';

document.addEventListener('DOMContentLoaded', () => {
  const dateInput = document.createElement('input');
  dateInput.setAttribute('type', 'text');
  dateInput.setAttribute('placeholder', 'Select a date...');
  dateInput.classList.add('my-datepicker');
  document.body.appendChild(dateInput);

  flatpickr('.my-datepicker', {
    locale: French,
    enableTime: true,
    dateFormat: 'Y-m-d H:i',
    altInput: true,
    altFormat: 'F j, Y at H:i',
    minDate: 'today',
    onReady: (selectedDates, dateStr, instance) => {
      console.log('Flatpickr is ready!', dateStr);
    },
  });

  const rangeInput = document.createElement('input');
  rangeInput.setAttribute('type', 'text');
  rangeInput.setAttribute('placeholder', 'Select date range...');
  rangeInput.classList.add('my-range-picker');
  document.body.appendChild(rangeInput);

  flatpickr('.my-range-picker', {
    mode: 'range',
    dateFormat: 'Y-m-d',
    altInput: true,
    altFormat: 'Y-m-d',
    onClose: (selectedDates, dateStr, instance) => {
      if (selectedDates.length === 2) {
        console.log('Selected range:', dateStr);
      }
    },
  });
});

view raw JSON →