@date-io/date-fns is a TypeScript adapter that provides a unified interface for the date-fns date manipulation library. It enables date-fns to be used interchangeably with other date libraries (moment, luxon, dayjs) in the date-io ecosystem, allowing developers to switch between different date libraries without changing application code.
npm install @date-io/date-fns date-fnsimport DateFnsUtils from "@date-io/date-fns";Named import (alternative):
import { default as DateFnsUtils } from "@date-io/date-fns";For CommonJS:
const DateFnsUtils = require("@date-io/date-fns").default;import DateFnsUtils from "@date-io/date-fns";
import { enUS } from "date-fns/locale/en-US";
// Create adapter instance
const dateFns = new DateFnsUtils({
locale: enUS,
formats: {
fullDate: "PPP" // Override default formats if needed
}
});
// Create and manipulate dates
const today = dateFns.date(); // Current date
const specificDate = dateFns.date("2024-01-15T10:30:00Z");
// Format dates
const formatted = dateFns.format(today, "fullDate"); // "January 15, 2024"
const customFormat = dateFns.formatByString(today, "yyyy-MM-dd");
// Date arithmetic
const nextWeek = dateFns.addWeeks(today, 1);
const daysDiff = dateFns.getDiff(nextWeek, today, "days"); // 7
// Validation and comparison
const isValid = dateFns.isValid(specificDate); // true
const isSame = dateFns.isSameDay(today, specificDate);The @date-io/date-fns adapter is built around several key concepts:
Create and configure the DateFnsUtils adapter instance.
/**
* DateFnsUtils adapter class implementing IUtils interface
*/
class DateFnsUtils implements IUtils<Date, Locale> {
constructor(options?: {
formats?: Partial<DateIOFormats>;
locale?: Locale;
instance?: any;
});
/** Name of the underlying library */
lib: string; // "date-fns"
/** Current locale configuration */
locale?: Locale;
/** Format strings for various date/time representations */
formats: DateIOFormats;
}
type Locale = typeof import("date-fns/locale/en-US").default;Core functionality for creating and converting Date objects.
/**
* Creates a date object with generic type support
* @param value - Optional date value (string, number, Date, or undefined)
* @returns Date object, null if input was null, current date if undefined
*/
date<
TArg extends unknown = undefined,
TRes extends unknown = TArg extends null
? null
: TArg extends undefined
? Date
: Date | null
>(value?: TArg): TRes;
/**
* Convert date to JavaScript Date object (identity function for native dates)
* @param value - Date to convert
* @returns JavaScript Date object
*/
toJsDate(value: Date): Date;
/**
* Parse ISO date string
* @param isoString - ISO 8601 date string
* @returns Parsed date object
*/
parseISO(isoString: string): Date;
/**
* Convert date to ISO string
* @param value - Date to convert
* @returns ISO 8601 formatted string
*/
toISO(value: Date): string;
/**
* Parse date string with custom format
* @param value - Date string to parse
* @param formatString - Format pattern (date-fns format)
* @returns Parsed date or null if invalid
*/
parse(value: string, formatString: string): Date | null;Methods for validating dates and performing comparisons.
/**
* Check if date is valid
* @param value - Value to validate
* @returns True if valid date
*/
isValid(value: any): boolean;
/**
* Check if date is null
* @param date - Date to check
* @returns True if date is null
*/
isNull(date: Date): boolean;
/**
* Compare dates for equality
* @param date - First date
* @param comparing - Second date
* @returns True if dates are equal
*/
isEqual(date: any, comparing: any): boolean;
/**
* Check if dates are on the same day
* @param value - First date
* @param comparing - Second date
* @returns True if same day
*/
isSameDay(value: Date, comparing: Date): boolean;
/**
* Check if dates are in the same month
* @param value - First date
* @param comparing - Second date
* @returns True if same month
*/
isSameMonth(value: Date, comparing: Date): boolean;
/**
* Check if dates are in the same year
* @param value - First date
* @param comparing - Second date
* @returns True if same year
*/
isSameYear(value: Date, comparing: Date): boolean;
/**
* Check if dates are in the same hour
* @param value - First date
* @param comparing - Second date
* @returns True if same hour
*/
isSameHour(value: Date, comparing: Date): boolean;Methods for checking date ordering and ranges.
/**
* Check if first date is after second date
* @param value - First date
* @param comparing - Second date
* @returns True if first date is after second
*/
isAfter(value: Date, comparing: Date): boolean;
/**
* Check if first date is before second date
* @param value - First date
* @param comparing - Second date
* @returns True if first date is before second
*/
isBefore(value: Date, comparing: Date): boolean;
/**
* Check if date is after the end of another day
* @param date - Date to check
* @param value - Reference date
* @returns True if date is after end of reference day
*/
isAfterDay(date: Date, value: Date): boolean;
/**
* Check if date is before the start of another day
* @param date - Date to check
* @param value - Reference date
* @returns True if date is before start of reference day
*/
isBeforeDay(date: Date, value: Date): boolean;
/**
* Check if date is after the end of another year
* @param date - Date to check
* @param value - Reference date
* @returns True if date is after end of reference year
*/
isAfterYear(date: Date, value: Date): boolean;
/**
* Check if date is before the start of another year
* @param date - Date to check
* @param value - Reference date
* @returns True if date is before start of reference year
*/
isBeforeYear(date: Date, value: Date): boolean;
/**
* Check if date is after the start of another month
* @param value - Date to check
* @param comparing - Reference date
* @returns True if date is after start of reference month
*/
isAfterMonth(value: Date, comparing: Date): boolean;
/**
* Check if date is before the start of another month
* @param value - Date to check
* @param comparing - Reference date
* @returns True if date is before start of reference month
*/
isBeforeMonth(value: Date, comparing: Date): boolean;
/**
* Check if date is within a range (inclusive)
* @param date - Date to check
* @param range - Array containing start and end dates
* @returns True if date is within range
*/
isWithinRange(date: Date, range: [Date, Date]): boolean;Methods for getting the start and end of various time periods.
/**
* Get start of day (00:00:00.000)
* @param value - Input date
* @returns Date at start of day
*/
startOfDay(value: Date): Date;
/**
* Get end of day (23:59:59.999)
* @param value - Input date
* @returns Date at end of day
*/
endOfDay(value: Date): Date;
/**
* Get start of week (locale-aware)
* @param value - Input date
* @returns Date at start of week
*/
startOfWeek(value: Date): Date;
/**
* Get end of week (locale-aware)
* @param value - Input date
* @returns Date at end of week
*/
endOfWeek(value: Date): Date;
/**
* Get start of month
* @param value - Input date
* @returns Date at start of month
*/
startOfMonth(value: Date): Date;
/**
* Get end of month
* @param value - Input date
* @returns Date at end of month
*/
endOfMonth(value: Date): Date;
/**
* Get start of year
* @param value - Input date
* @returns Date at start of year
*/
startOfYear(value: Date): Date;
/**
* Get end of year
* @param value - Input date
* @returns Date at end of year
*/
endOfYear(value: Date): Date;Methods for adding time intervals to dates and calculating differences.
/**
* Add seconds to a date
* @param value - Input date
* @param count - Number of seconds to add
* @returns New date with seconds added
*/
addSeconds(value: Date, count: number): Date;
/**
* Add minutes to a date
* @param value - Input date
* @param count - Number of minutes to add
* @returns New date with minutes added
*/
addMinutes(value: Date, count: number): Date;
/**
* Add hours to a date
* @param value - Input date
* @param count - Number of hours to add
* @returns New date with hours added
*/
addHours(value: Date, count: number): Date;
/**
* Add days to a date
* @param value - Input date
* @param count - Number of days to add
* @returns New date with days added
*/
addDays(value: Date, count: number): Date;
/**
* Add weeks to a date
* @param value - Input date
* @param count - Number of weeks to add
* @returns New date with weeks added
*/
addWeeks(value: Date, count: number): Date;
/**
* Add months to a date
* @param value - Input date
* @param count - Number of months to add
* @returns New date with months added
*/
addMonths(value: Date, count: number): Date;
/**
* Add years to a date
* @param value - Input date
* @param count - Number of years to add
* @returns New date with years added
*/
addYears(value: Date, count: number): Date;
/**
* Calculate difference between dates in specified unit
* @param value - First date
* @param comparing - Second date or string
* @param unit - Unit of measurement (optional, defaults to milliseconds)
* @returns Difference in specified unit
*/
getDiff(value: Date, comparing: Date | string, unit?: Unit): number;Methods for getting and setting individual date components.
/**
* Get hours from date (0-23)
* @param value - Input date
* @returns Hours value
*/
getHours(value: Date): number;
/**
* Set hours on date
* @param value - Input date
* @param count - Hours value (0-23)
* @returns New date with hours set
*/
setHours(value: Date, count: number): Date;
/**
* Get minutes from date (0-59)
* @param date - Input date
* @returns Minutes value
*/
getMinutes(date: Date): number;
/**
* Set minutes on date
* @param value - Input date
* @param count - Minutes value (0-59)
* @returns New date with minutes set
*/
setMinutes(value: Date, count: number): Date;
/**
* Get seconds from date (0-59)
* @param value - Input date
* @returns Seconds value
*/
getSeconds(value: Date): number;
/**
* Set seconds on date
* @param value - Input date
* @param count - Seconds value (0-59)
* @returns New date with seconds set
*/
setSeconds(value: Date, count: number): Date;
/**
* Get day of month from date (1-31)
* @param date - Input date
* @returns Day of month value
*/
getDate(date: Date): number;
/**
* Set day of month on date
* @param date - Input date
* @param count - Day value (1-31)
* @returns New date with day set
*/
setDate(date: Date, count: number): Date;
/**
* Get week number from date
* @param date - Input date
* @returns Week number
*/
getWeek(date: Date): number;
/**
* Get month from date (0-11)
* @param date - Input date
* @returns Month value (0-11)
*/
getMonth(date: Date): number;
/**
* Get number of days in month
* @param date - Input date
* @returns Number of days in the month
*/
getDaysInMonth(date: Date): number;
/**
* Set month on date
* @param date - Input date
* @param count - Month value (0-11)
* @returns New date with month set
*/
setMonth(date: Date, count: number): Date;
/**
* Get full year from date
* @param value - Input date
* @returns Full year value
*/
getYear(value: Date): number;
/**
* Set year on date
* @param value - Input date
* @param count - Year value
* @returns New date with year set
*/
setYear(value: Date, count: number): Date;Methods for converting dates to formatted strings.
/**
* Format date using predefined format key
* @param date - Date to format
* @param formatKey - Key from DateIOFormats
* @returns Formatted date string
*/
format(date: Date, formatKey: keyof DateIOFormats): string;
/**
* Format date using custom format string
* @param date - Date to format
* @param formatString - Custom format pattern (date-fns format)
* @returns Formatted date string
*/
formatByString(date: Date, formatString: string): string;
/**
* Format number (identity function)
* @param numberToFormat - Number string to format
* @returns Formatted number string
*/
formatNumber(numberToFormat: string): string;
/**
* Get AM/PM text for meridiem
* @param ampm - "am" or "pm"
* @returns "AM" or "PM"
*/
getMeridiemText(ampm: "am" | "pm"): string;Methods for handling locales and internationalization.
/**
* Get current locale code
* @returns Locale code string (e.g., "en-US")
*/
getCurrentLocaleCode(): string;
/**
* Check if current locale uses 12-hour clock
* @returns True if 12-hour format is used
*/
is12HourCycleInCurrentLocale(): boolean;
/**
* Get human-readable format help text
* @param format - Format string
* @returns Helper text for the format
*/
getFormatHelperText(format: string): string;Methods for navigating between dates and generating date arrays.
/**
* Get next month from date
* @param date - Input date
* @returns Date in next month
*/
getNextMonth(date: Date): Date;
/**
* Get previous month from date
* @param date - Input date
* @returns Date in previous month
*/
getPreviousMonth(date: Date): Date;
/**
* Get array of 12 months starting from year start
* @param date - Reference date
* @returns Array of 12 date objects representing months
*/
getMonthArray(date: Date): Date[];
/**
* Get localized weekday names (abbreviated)
* @returns Array of abbreviated weekday names
*/
getWeekdays(): string[];
/**
* Get calendar month as 2D array of weeks
* @param date - Reference date
* @returns 2D array where each sub-array represents a week
*/
getWeekArray(date: Date): Date[][];
/**
* Get array of years in range
* @param start - Start date
* @param end - End date
* @returns Array of date objects representing years
*/
getYearRange(start: Date, end: Date): Date[];
/**
* Combine date and time components
* @param date - Date component
* @param time - Time component
* @returns New date with combined date and time
*/
mergeDateAndTime(date: Date, time: Date): Date;/**
* Format strings for various date/time representations
*/
interface DateIOFormats {
/** Localized full date @example "Jan 1, 2019" */
fullDate: string;
/** Partially localized full date with weekday @example "Tuesday, January 1, 2019" */
fullDateWithWeekday: string;
/** Date format with month and day @example "1 January" */
normalDate: string;
/** Date format with weekday, month and day @example "Wed, Jan 1" */
normalDateWithWeekday: string;
/** Shorter day format @example "Jan 1" */
shortDate: string;
/** Year format @example "2019" */
year: string;
/** Month format @example "January" */
month: string;
/** Short month format @example "Jan" */
monthShort: string;
/** Month with year format @example "January 2018" */
monthAndYear: string;
/** Month with date format @example "January 1" */
monthAndDate: string;
/** Weekday format @example "Wednesday" */
weekday: string;
/** Short weekday format @example "Wed" */
weekdayShort: string;
/** Day format @example "1" */
dayOfMonth: string;
/** Hours format 12h @example "11" */
hours12h: string;
/** Hours format 24h @example "23" */
hours24h: string;
/** Minutes format @example "44" */
minutes: string;
/** Seconds format @example "00" */
seconds: string;
/** Full time localized format @example "11:44 PM" for US, "23:44" for Europe */
fullTime: string;
/** Full time 12h format @example "11:44 PM" */
fullTime12h: string;
/** Full time 24h format @example "23:44" */
fullTime24h: string;
/** Date & time with localized time @example "Jan 1, 2018 11:44 PM" */
fullDateTime: string;
/** Date & time 12h format @example "Jan 1, 2018 11:44 PM" */
fullDateTime12h: string;
/** Date & time 24h format @example "Jan 1, 2018 23:44" */
fullDateTime24h: string;
/** Keyboard input friendly date @example "02/13/2020" */
keyboardDate: string;
/** Keyboard input friendly date/time @example "02/13/2020 23:44" */
keyboardDateTime: string;
/** Keyboard input friendly date/time 12h @example "02/13/2020 11:44 PM" */
keyboardDateTime12h: string;
/** Keyboard input friendly date/time 24h @example "02/13/2020 23:44" */
keyboardDateTime24h: string;
}
/**
* Time unit for difference calculations
*/
type Unit =
| "years"
| "quarters"
| "months"
| "weeks"
| "days"
| "hours"
| "minutes"
| "seconds"
| "milliseconds";
/**
* IUtils interface from @date-io/core
*/
interface IUtils<TDate, TLocale> {
formats: DateIOFormats;
locale?: TLocale;
lib: string;
// ... all methods listed above
}