or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

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

index.mddocs/

Flatpickr

Flatpickr is a lightweight, powerful JavaScript datetime picker that provides a dependency-free solution for date and time input. It offers extensive customization options including date ranges, multiple date selections, time-only picking, human-friendly formatting, and the ability to disable specific dates using arbitrary logic.

Package Information

  • Package Name: flatpickr
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install flatpickr

Core Imports

import flatpickr from "flatpickr";

For TypeScript with types:

import flatpickr from "flatpickr";

// Import types from the flatpickr namespace
type Instance = flatpickr.Instance;
type CustomLocale = flatpickr.CustomLocale;
type Locale = flatpickr.Locale;

// Import nested option types
type Options = flatpickr.Options.Options;
type Hook = flatpickr.Options.Hook;
type DateOption = flatpickr.Options.DateOption;
type Plugin = flatpickr.Options.Plugin;

For CommonJS:

const flatpickr = require("flatpickr");

For browser usage:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/flatpickr/dist/flatpickr.min.css">
<script src="https://cdn.jsdelivr.net/npm/flatpickr"></script>

Basic Usage

import flatpickr from "flatpickr";

// Basic date picker
const fp = flatpickr("#my-input", {
  dateFormat: "Y-m-d",
  defaultDate: "today"
});

// Date range picker
const rangePicker = flatpickr("#range-input", {
  mode: "range",
  dateFormat: "Y-m-d",
});

// Date and time picker
const datetimePicker = flatpickr("#datetime-input", {
  enableTime: true,
  dateFormat: "Y-m-d H:i",
  time_24hr: true
});

Architecture

Flatpickr is built around several key components:

  • Main Factory Function: flatpickr() creates instances from selectors and configuration
  • Instance API: Each picker instance provides methods for programmatic control
  • Configuration System: Extensive options for customizing behavior and appearance
  • Hook System: Event handlers for responding to user interactions and state changes
  • Plugin Architecture: Extensible plugin system for additional functionality
  • Localization: Support for 51+ languages with customizable locale objects
  • Theme System: Multiple CSS themes for different visual styles

Capabilities

Core Functionality

Main flatpickr factory function and instance creation. Essential for initializing date pickers and managing multiple instances.

function flatpickr(
  selector: Node | ArrayLike<Node> | string,
  config?: Options
): Instance | Instance[];

interface FlatpickrFn {
  defaultConfig: Partial<ParsedOptions>;
  l10ns: { [k in LocaleKey]?: CustomLocale } & { default: Locale };
  localize: (l10n: CustomLocale) => void;
  setDefaults: (config: Options) => void;
  parseDate: (date: DateOption, format?: string, timeless?: boolean) => Date | undefined;
  formatDate: (date: Date, format: string) => string;
  compareDates: (date1: Date, date2: Date, timeless?: boolean) => number;
}

Core Functionality

Instance Management

Instance control methods for programmatic interaction with date pickers. Provides methods to open, close, set dates, and update configuration after initialization.

interface Instance {
  // State management
  open: (e?: FocusEvent | MouseEvent, positionElement?: HTMLElement) => void;
  close: () => void;
  toggle: () => void;
  destroy: () => void;
  
  // Date manipulation
  setDate: (date: DateOption | DateOption[], triggerChange?: boolean, format?: string) => void;
  clear: (emitChangeEvent?: boolean, toInitial?: boolean) => void;
  jumpToDate: (date?: DateOption, triggerChange?: boolean) => void;
  
  // Configuration
  set: (option: keyof Options | { [k in keyof Options]?: Options[k] }, value?: any) => void;
  redraw: () => void;
}

Instance Management

Configuration Options

Comprehensive configuration system for customizing flatpickr behavior, appearance, and functionality. Covers date formats, selection modes, validation, and UI customization.

interface Options {
  // Core options
  mode: "single" | "multiple" | "range" | "time";
  dateFormat: string;
  enableTime: boolean;
  time_24hr: boolean;
  
  // Date constraints
  minDate: DateOption;
  maxDate: DateOption;
  disable: DateLimit[];
  enable: DateLimit[];
  
  // UI behavior
  clickOpens: boolean;
  closeOnSelect: boolean;
  allowInput: boolean;
  inline: boolean;
  static: boolean;
  
  // Event hooks
  onChange: Hook[];
  onOpen: Hook[];
  onClose: Hook[];
  onReady: Hook[];
  onDayCreate: Hook[];
  onDestroy: Hook[];
  onMonthChange: Hook[];
  onYearChange: Hook[];
  onValueUpdate: Hook[];
}

Configuration Options

Localization

Internationalization support with 51+ built-in locales and customizable locale objects. Enables date picker localization for global applications.

interface Locale {
  weekdays: {
    shorthand: [string, string, string, string, string, string, string];
    longhand: [string, string, string, string, string, string, string];
  };
  months: {
    shorthand: [string, string, string, string, string, string, string, string, string, string, string, string];
    longhand: [string, string, string, string, string, string, string, string, string, string, string, string];
  };
  firstDayOfWeek: number;
  ordinal: (nth: number) => string;
  rangeSeparator: string;
  time_24hr: boolean;
}

type CustomLocale = Partial<Locale>;

Localization

Plugin System

Extensible plugin architecture for adding specialized functionality. Includes built-in plugins for ranges, time constraints, integrations, and UI enhancements.

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

// Built-in plugins
import { rangePlugin } from "flatpickr/dist/plugins/rangePlugin";
import { minMaxTimePlugin } from "flatpickr/dist/plugins/minMaxTimePlugin";
import { momentPlugin } from "flatpickr/dist/plugins/momentPlugin";
import { scrollPlugin } from "flatpickr/dist/plugins/scrollPlugin";

Plugin System

Type Definitions

type DateOption = Date | string | number;
type DateLimit<D = DateOption> = D | DateRangeLimit<D> | ((date: Date) => boolean);
type DateRangeLimit<D = DateOption> = { from: D; to: D };

type Hook = (
  dates: Date[],
  currentDateString: string,
  self: Instance,
  data?: any
) => void;

type HookKey = 
  | "onChange" 
  | "onClose" 
  | "onDayCreate" 
  | "onDestroy" 
  | "onKeyDown"
  | "onMonthChange" 
  | "onOpen" 
  | "onParseConfig" 
  | "onReady" 
  | "onValueUpdate"
  | "onYearChange" 
  | "onPreCalendarPosition";