Year Select Plugin for Flatpickr

A plugin for flatpickr that transforms the date picker into a year selector with a decade-based navigation interface.

Support me

If you like what I'm doing, please support me: https://ko-fi.com/mykeshato

Installation

npm install flatpickr
# or
yarn add flatpickr

The plugin is imported separately:

import flatpickr from 'flatpickr';
import yearSelectPlugin from './path-to-yearSelectPlugin';

Basic Usage

import flatpickr from 'flatpickr';
import yearSelectPlugin from './yearSelectPlugin';

flatpickr('#my-input', {
  plugins: [yearSelectPlugin()]
});

Configuration

The plugin accepts an optional configuration object:

interface Config {
  dateFormat: string; // Format for storing date value
  altFormat: string; // Format for displaying date
  theme: string; // Theme for styling ('light' by default)
}

Default Configuration

const defaultConfig = {
  dateFormat: 'Y', // Year format (YYYY)
  altFormat: 'Y', // Display format (YYYY)
  theme: 'light' // Default theme
};

Example with Custom Configuration

flatpickr('#year-picker', {
  plugins: [
    yearSelectPlugin({
      dateFormat: 'Y-m-d',
      altFormat: 'Y',
      theme: 'dark'
    })
  ]
});

Features

Decade Navigation

• Years are displayed in a decade view (e.g., 2020-2029)
• Previous button (←) navigates to the previous decade
• Next button (→) navigates to the next decade

Year Selection

• Single Mode: Select a single year
• Range Mode: Select a range of years
• Multiple Mode: Select multiple years

Keyboard Navigation

The plugin supports keyboard navigation:

• Arrow keys to navigate between years
• Enter to select the focused year

Key	Action
ArrowLeft	Move left
ArrowRight	Move right
ArrowUp	Move up
ArrowDown	Move down
Enter	Select focused year

Examples

Single Year Selection

import flatpickr from 'flatpickr';
import yearSelectPlugin from './yearSelectPlugin';

flatpickr('#year-single', {
  plugins: [yearSelectPlugin()],
  mode: 'single'
});

Year Range Selection

import flatpickr from 'flatpickr';
import yearSelectPlugin from './yearSelectPlugin';

flatpickr('#year-range', {
  plugins: [yearSelectPlugin()],
  mode: 'range'
});

With Min and Max Date Constraints

import flatpickr from 'flatpickr';
import yearSelectPlugin from './yearSelectPlugin';

flatpickr('#year-constrained', {
  plugins: [yearSelectPlugin()],
  minDate: '2010-01-01',
  maxDate: '2030-12-31'
});

Styling

The plugin adds the class flatpickr-yearSelect-theme-{theme} to the calendar container, where {theme} is the theme specified in the config (defaults to 'light').

CSS Classes

The plugin uses the following CSS classes:

• flatpickr-yearSelect-years: Container for year elements
• flatpickr-yearSelect-year: Individual year element
• flatpickr-yearSelect-range: Element displaying current decade range (e.g., "2020 - 2029")
• today: Applied to the current year
• selected: Applied to selected year(s)
• flatpickr-yearSelect-theme-light: Applied when using the 'light' theme
• flatpickr-yearSelect-theme-dark: Applied when using the 'dark' theme

Advanced Usage

Integration with Form Submission

import flatpickr from 'flatpickr';
import yearSelectPlugin from './yearSelectPlugin';

const yearPicker = flatpickr('#year-input', {
  plugins: [yearSelectPlugin()],
  onChange: (selectedDates, dateStr) => {
    console.log('Selected year:', dateStr);
    document.getElementById('hidden-year-value').value = dateStr;
  }
});

// Form submission example
document.getElementById('my-form').addEventListener('submit', (e) => {
  e.preventDefault();
  const selectedYear = document.getElementById('hidden-year-value').value;
  // Process form data
});

Custom Event Handling

import flatpickr from 'flatpickr';
import yearSelectPlugin from './yearSelectPlugin';

const yearPicker = flatpickr('#year-custom', {
  plugins: [yearSelectPlugin()],
  onYearChange: (selectedDates, dateStr) => {
    // Custom logic when year changes
  },
  onClose: (selectedDates, dateStr) => {
    // Handle picker closing
  }
});

API Integration

Programmatically Set Year

import flatpickr from 'flatpickr';
import yearSelectPlugin from './yearSelectPlugin';

const yearPicker = flatpickr('#year-api', {
  plugins: [yearSelectPlugin()]
});

// Set to current year
document.getElementById('set-current-year').addEventListener('click', () => {
  const now = new Date();
  yearPicker.setDate(now);
});

// Set to specific year
document.getElementById('set-specific-year').addEventListener('click', () => {
  yearPicker.setDate('2025');
});

Getting Selected Year

const selectedYear = yearPicker.selectedDates[0].getFullYear();

Browser Compatibility

The plugin is compatible with all browsers supported by flatpickr. It uses modern JavaScript features, so older browsers may require appropriate polyfills.

License

MIT © MikeSha