Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
flatpickr
✓ import flatpickr from 'flatpickr';
✗ const flatpickr = require('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
✓ import 'flatpickr/dist/flatpickr.min.css';
✗ import 'flatpickr/flatpickr.min.css';
Always import the CSS for styling. You can also import specific themes like `flatpickr/dist/themes/material_green.css` instead.
Locale
✓ import { German } from 'flatpickr/dist/l10n/de';
✗ import { de } from 'flatpickr/dist/l10n/de.js';
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({})] }`.
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);
}
},
});
});
Debug
Known issues
breakingVersions 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.fixUpdate flatpickr to version 4.6.11 or later: `npm install flatpickr@latest`.
affects: <4.6.11
gotchaWhen 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.
gotchaFlatpickr 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.
gotchaIf 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.
gotchaWhen 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.
gotchaIn 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.
Errors
Common errors & fixes
TypeError: flatpickr is not a function
The `flatpickr` function was not imported or loaded correctly, or the script tag was placed before the element it targets.
fixEnsure 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
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.
fixVerify 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'
The CSS import path is incorrect or the `flatpickr` package is not correctly installed in `node_modules`.
fixCheck 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
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.
fixEnsure 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>`.
Audit
Dependencies
No dependency data recorded yet.