flatpickr-year-select-plugin

v1.3.1

Published

22 days ago

change year selection box

Downloads

333

0High
0Medium
0Low

bearholmes

flatpickr Year Select Plugin

A modern flatpickr plugin that replaces the default year input with a customizable dropdown select.

Demo • Installation • Usage • API

✨ Features

🎯 Easy Integration - Drop-in replacement for the default year selector
🎨 Theme Compatible - Works seamlessly with all flatpickr themes
⚡ Lightweight - Minimal overhead (~2.5KB gzipped)
♿ Accessible - Fully keyboard navigable with ARIA labels
🔧 Configurable - Customize the year range to your needs
📦 TypeScript Support - Full type definitions included
🌐 Multi-Instance Safe - Use multiple instances on the same page
🔄 Constraint-Aware - Clamps options to minDate/maxDate (even when changed at runtime) and syncs with current/selected/default year; supports array defaultDate by using the first valid entry

📦 Installation

npm install flatpickr flatpickr-year-select-plugin

or with yarn:

yarn add flatpickr flatpickr-year-select-plugin

or with a CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/flatpickr/dist/flatpickr.min.css" />
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/flatpickr-year-select-plugin/dist/yearSelectPlugin.min.css"
/>

<script src="https://cdn.jsdelivr.net/npm/flatpickr"></script>
<script src="https://cdn.jsdelivr.net/npm/flatpickr-year-select-plugin/dist/flatpickr-year-select-plugin.umd.js"></script>

🚀 Usage

Basic Example

import flatpickr from 'flatpickr';
import yearSelectPlugin from 'flatpickr-year-select-plugin';
import 'flatpickr-year-select-plugin/dist/yearSelectPlugin.min.css';

flatpickr('#myInput', {
  plugins: [yearSelectPlugin()],
});

With Custom Range

flatpickr('#myInput', {
  plugins: [
    yearSelectPlugin({
      start: 5, // Show 5 years before current year
      end: 5, // Show 5 years after current year
    }),
  ],
});

With Date Constraints

flatpickr('#myInput', {
  minDate: '2020-01-01',
  maxDate: '2030-12-31',
  plugins: [yearSelectPlugin()],
  // The plugin automatically respects minDate and maxDate
});

TypeScript

import flatpickr from 'flatpickr';
import yearSelectPlugin from 'flatpickr-year-select-plugin';
import type { YearDropdownPluginConfig } from 'flatpickr-year-select-plugin';

const config: YearDropdownPluginConfig = {
  start: 10,
  end: 10,
};

flatpickr('#myInput', {
  plugins: [yearSelectPlugin(config)],
});

🎨 Demo

Basic Year Selector

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/flatpickr/dist/flatpickr.min.css" />
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/flatpickr-year-select-plugin/dist/yearSelectPlugin.min.css"
    />
  </head>
  <body>
    <input type="text" id="demo" placeholder="Select a date" />

    <script src="https://cdn.jsdelivr.net/npm/flatpickr"></script>
    <script src="https://cdn.jsdelivr.net/npm/flatpickr-year-select-plugin/dist/flatpickr-year-select-plugin.umd.js"></script>
    <script>
      flatpickr('#demo', {
        plugins: [yearSelectPlugin()],
      });
    </script>
  </body>
</html>

GitHub Pages demo: this repository ships a Pages workflow (.github/workflows/pages.yml) that builds the package and publishes demo/index.html with the built assets from dist/. Once Pages is enabled in repository settings, the workflow will deploy on pushes to main.

📖 API

Plugin Configuration

| Option | Type | Default | Description | | ------- | -------- | ------- | ----------------------------------------------- | | start | number | 3 | Number of years to show before the current year | | end | number | 3 | Number of years to show after the current year |

Behavior

If minDate is set in flatpickr config, the year range start is automatically adjusted
If maxDate is set in flatpickr config, the year range end is automatically adjusted
The plugin respects all flatpickr date constraints, clamps options to current minDate/maxDate (including values changed at runtime), and anchors/synchronizes the dropdown with the picker’s current/selected/default year (falls back to today). Options regenerate on open/year change to stay in sync with constraints and the calendar view.
defaultDate arrays (multi/range) are supported; the first valid date is used to anchor the initial dropdown range.
Internal clamping avoids redundant changeYear calls; calendar view and dropdown stay aligned without extra hook noise.
Multiple instances on the same page work independently

🔧 Compatibility

flatpickr: v4.6.0 or higher
Browsers: All modern browsers (Chrome, Firefox, Safari, Edge)
Frameworks: Works with React, Vue, Angular, Svelte, and vanilla JS

🛠️ Development

# Install dependencies
npm install

# Build the project
npm run build

# Build JavaScript only
npm run build-js

# Build CSS only
npm run build-css

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Type check
npm run type-check

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Make your changes and add tests if applicable
Run the test suite (npm test)
Ensure linting passes (npm run lint)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Please ensure your code:

Passes all existing tests
Includes tests for new functionality
Follows the existing code style (enforced by ESLint and Prettier)
Maintains or improves code coverage

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

@bearholmes

🙏 Acknowledgments

Built for flatpickr by Gregory
Inspired by the need for better year selection UX

Made with ❤️ by bearholmes