or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

core-api.md index.md localization.md plugins.md

tile.json

Plugins

Day.js uses a plugin system to keep the core library small while providing extensive functionality through optional plugins. This enables tree-shaking and allows users to include only the features they need.

Capabilities

Plugin System Core

The plugin system allows extending Day.js with additional functionality through a simple registration mechanism.

/**
 * Extend dayjs with plugin functionality
 * @param plugin - Plugin function that extends Day.js
 * @param option - Optional configuration for the plugin
 * @returns dayjs function for chaining
 */
dayjs.extend<T = unknown>(plugin: PluginFunc<T>, option?: T): typeof dayjs;

/**
 * Plugin function interface
 * @param option - Plugin options passed during registration
 * @param dayjsClass - Dayjs constructor class
 * @param dayjsFactory - Main dayjs factory function
 */
interface PluginFunc<T = unknown> {
  (option: T, dayjsClass: typeof Dayjs, dayjsFactory: typeof dayjs): void;
}

Usage Examples:

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';
import relativeTime from 'dayjs/plugin/relativeTime';

// Install plugins
dayjs.extend(utc);
dayjs.extend(timezone);
dayjs.extend(relativeTime, {
  thresholds: [
    { l: 's', r: 44, d: 'second' },
    { l: 'm', r: 89 },
    { l: 'mm', r: 44, d: 'minute' }
  ]
});

// Plugins are now available
const utcDate = dayjs.utc();
const timeInTokyo = dayjs().tz('Asia/Tokyo');
const relative = dayjs().fromNow();

Essential Plugins

UTC Plugin

Adds UTC mode support for parsing and displaying dates in UTC timezone.

/**
 * Parse date in UTC mode
 * @param date - Input date to parse
 * @returns Dayjs instance in UTC mode
 */
dayjs.utc(date?: ConfigType): Dayjs;

/**
 * Convert instance to UTC mode
 * @param keepLocalTime - Preserve local time when converting
 * @returns New Dayjs instance in UTC mode
 */
utc(keepLocalTime?: boolean): Dayjs;

/**
 * Convert instance to local timezone
 * @returns New Dayjs instance in local timezone
 */
local(): Dayjs;

/**
 * Check if instance is in UTC mode
 * @returns True if instance is in UTC mode
 */
isUTC(): boolean;

/**
 * Set or get UTC offset in minutes
 * @param input - Offset in minutes or offset string
 * @param keepLocalTime - Preserve local time when setting offset
 * @returns Current offset or new instance with offset
 */
utcOffset(): number;
utcOffset(input: number | string, keepLocalTime?: boolean): Dayjs;

Usage Examples:

import utc from 'dayjs/plugin/utc';
dayjs.extend(utc);

// Parse in UTC
const utcDate = dayjs.utc('2018-04-04T16:00:00.000Z');
const utcNow = dayjs.utc();

// Convert to/from UTC
const localDate = dayjs();
const asUtc = localDate.utc(); // Convert to UTC
const backToLocal = asUtc.local(); // Convert back to local

// UTC offset operations
console.log(dayjs().utcOffset()); // Current offset in minutes
const offsetDate = dayjs().utcOffset(480); // Set to +08:00
const withStringOffset = dayjs().utcOffset('+08:00');

// Check UTC mode
console.log(dayjs.utc().isUTC()); // true
console.log(dayjs().isUTC()); // false

Timezone Plugin

Comprehensive timezone support using IANA timezone database.

/**
 * Parse date in specific timezone
 * @param date - Input date
 * @param timezone - IANA timezone name
 * @returns Dayjs instance in specified timezone
 */
dayjs.tz(date?: ConfigType, timezone?: string): Dayjs;
dayjs.tz(date: ConfigType, format: string, timezone?: string): Dayjs;

/**
 * Convert instance to specific timezone
 * @param timezone - IANA timezone name
 * @param keepLocalTime - Preserve local time when converting
 * @returns New Dayjs instance in specified timezone
 */
tz(timezone?: string, keepLocalTime?: boolean): Dayjs;

/**
 * Get timezone offset name
 * @param type - Format type ('short' or 'long')
 * @returns Timezone offset name
 */
offsetName(type?: 'short' | 'long'): string | undefined;

/**
 * Guess the current timezone
 * @returns IANA timezone name
 */
dayjs.tz.guess(): string;

/**
 * Set default timezone for dayjs.tz()
 * @param timezone - Default IANA timezone name
 */
dayjs.tz.setDefault(timezone?: string): void;

Usage Examples:

import timezone from 'dayjs/plugin/timezone';
import utc from 'dayjs/plugin/utc'; // Required dependency

dayjs.extend(utc);
dayjs.extend(timezone);

// Parse in timezone
const tokyoTime = dayjs.tz('2018-04-04 16:00', 'Asia/Tokyo');
const nyTime = dayjs.tz('2018-04-04 16:00', 'America/New_York');

// Convert between timezones
const utcTime = dayjs.utc();
const inTokyo = utcTime.tz('Asia/Tokyo');
const inLondon = utcTime.tz('Europe/London');

// Timezone information
console.log(dayjs().tz('Asia/Tokyo').offsetName()); // 'JST'
console.log(dayjs().tz('America/New_York').offsetName('long')); // 'Eastern Standard Time'

// Guess current timezone
console.log(dayjs.tz.guess()); // 'America/New_York' (example)

// Set default timezone
dayjs.tz.setDefault('Asia/Tokyo');
const defaultTz = dayjs.tz('2018-04-04 16:00'); // Uses Tokyo timezone

Duration Plugin

Adds support for Duration objects representing time periods.

/**
 * Create a Duration instance
 * @param input - Duration input (number, string, or object)
 * @param unit - Time unit when input is number
 * @returns Duration instance
 */
dayjs.duration(input: DurationInputType, unit?: DurationUnitType): Duration;

/**
 * Check if value is a Duration instance
 * @param d - Value to check
 * @returns True if value is Duration
 */
dayjs.isDuration(d: any): d is Duration;

/**
 * Duration class for representing time periods
 */
interface Duration {
  /**
   * Add duration to Dayjs instance
   */
  add(input: DurationInputType, unit?: DurationUnitType): Duration;
  add(duration: Duration): Duration;
  
  /**
   * Subtract duration from Dayjs instance
   */
  subtract(input: DurationInputType, unit?: DurationUnitType): Duration;
  subtract(duration: Duration): Duration;
  
  /**
   * Get duration component value
   */
  milliseconds(): number;
  seconds(): number;
  minutes(): number;
  hours(): number;
  days(): number;
  weeks(): number;
  months(): number;
  years(): number;
  
  /**
   * Get duration as total value in unit
   */
  asMilliseconds(): number;
  asSeconds(): number;
  asMinutes(): number;
  asHours(): number;
  asDays(): number;
  asWeeks(): number;
  asMonths(): number;
  asYears(): number;
  
  /**
   * Get duration as value in specific unit
   */
  as(unit: DurationUnitType): number;
  get(unit: DurationUnitType): number;
  
  /**
   * Format duration as string
   */
  format(template?: string): string;
  toISOString(): string;
  toJSON(): string;
  
  /**
   * Humanize duration
   */
  humanize(withSuffix?: boolean): string;
  
  /**
   * Clone duration
   */
  clone(): Duration;
  
  /**
   * Set locale for duration
   */
  locale(locale: string): Duration;
}

type DurationUnitType = Exclude<OpUnitType, "date" | "dates">;
type DurationInputType = string | number | DurationUnitsObject;
interface DurationUnitsObject {
  years?: number;
  months?: number;
  weeks?: number;
  days?: number;
  hours?: number;
  minutes?: number;
  seconds?: number;
  milliseconds?: number;
}

Usage Examples:

import duration from 'dayjs/plugin/duration';
dayjs.extend(duration);

// Create durations
const dur1 = dayjs.duration(100); // 100 milliseconds
const dur2 = dayjs.duration(2, 'minutes');
const dur3 = dayjs.duration({ hours: 2, minutes: 30 });
const dur4 = dayjs.duration('PT2H30M'); // ISO 8601

// Duration arithmetic
const sum = dur2.add(30, 'seconds');
const diff = dur3.subtract(1, 'hour');

// Get components
console.log(dur3.hours()); // 2
console.log(dur3.minutes()); // 30

// Get as total values
console.log(dur3.asMinutes()); // 150
console.log(dur3.asHours()); // 2.5

// Format durations
console.log(dur3.format('H:mm')); // '2:30'
console.log(dur3.toISOString()); // 'PT2H30M'

// Humanize
console.log(dur2.humanize()); // '2 minutes'
console.log(dur2.humanize(true)); // 'in 2 minutes'

Relative Time Plugin

Adds methods for displaying relative time (e.g., "2 hours ago", "in 3 days").

/**
 * Display time from now
 * @param withoutSuffix - Omit 'ago' or 'in' suffix
 * @returns Relative time string
 */
fromNow(withoutSuffix?: boolean): string;

/**
 * Display time from another date
 * @param compared - Date to compare from
 * @param withoutSuffix - Omit 'ago' or 'in' suffix
 * @returns Relative time string
 */
from(compared: ConfigType, withoutSuffix?: boolean): string;

/**
 * Display time to now
 * @param withoutSuffix - Omit 'ago' or 'in' suffix
 * @returns Relative time string
 */
toNow(withoutSuffix?: boolean): string;

/**
 * Display time to another date
 * @param compared - Date to compare to
 * @param withoutSuffix - Omit 'ago' or 'in' suffix
 * @returns Relative time string
 */
to(compared: ConfigType, withoutSuffix?: boolean): string;

interface RelativeTimeOptions {
  rounding?: (num: number) => number;
  thresholds?: RelativeTimeThreshold[];
}

interface RelativeTimeThreshold {
  l: string; // threshold key
  r?: number; // range
  d?: string; // unit
}

Usage Examples:

import relativeTime from 'dayjs/plugin/relativeTime';
dayjs.extend(relativeTime);

const now = dayjs();
const pastDate = dayjs().subtract(2, 'hour');
const futureDate = dayjs().add(3, 'day');

// From now
console.log(pastDate.fromNow()); // '2 hours ago'
console.log(futureDate.fromNow()); // 'in 3 days'
console.log(pastDate.fromNow(true)); // '2 hours' (without suffix)

// To now
console.log(pastDate.toNow()); // 'in 2 hours'
console.log(futureDate.toNow()); // '3 days ago'

// From/to specific dates
const date1 = dayjs('2018-01-01');
const date2 = dayjs('2018-01-03');
console.log(date1.from(date2)); // '2 days ago'
console.log(date1.to(date2)); // 'in 2 days'

Formatting Plugins

Advanced Format Plugin

Adds additional format tokens for more formatting options.

// Additional format tokens available after installing advancedFormat plugin:
// Q - Quarter (1-4)
// Do - Day of month with ordinal (1st, 2nd, 3rd, etc.)
// k - Hour (1-24)
// kk - Hour, zero-padded (01-24)
// X - Unix timestamp (seconds)
// x - Unix timestamp (milliseconds)

Usage Examples:

import advancedFormat from 'dayjs/plugin/advancedFormat';
dayjs.extend(advancedFormat);

const date = dayjs('2018-04-04T16:00:00.000Z');

console.log(date.format('Q')); // 2 (quarter)
console.log(date.format('Do')); // 4th
console.log(date.format('k')); // 16 (hour 1-24)
console.log(date.format('kk')); // 16 (hour padded)
console.log(date.format('X')); // 1522857600 (unix seconds)
console.log(date.format('x')); // 1522857600000 (unix milliseconds)

// Combined usage
console.log(date.format('Qo [quarter], Do [day]')); // '2nd quarter, 4th day'

Localized Format Plugin

Adds localized formatting shortcuts that adapt to the current locale.

// Localized format tokens:
// L - Short date (MM/DD/YYYY or DD/MM/YYYY based on locale)
// LL - Medium date (MMMM D, YYYY)
// LLL - Long date with time (MMMM D, YYYY h:mm A)
// LLLL - Full date with day (dddd, MMMM D, YYYY h:mm A)
// LT - Time (h:mm A)
// LTS - Time with seconds (h:mm:ss A)

Usage Examples:

import localizedFormat from 'dayjs/plugin/localizedFormat';
dayjs.extend(localizedFormat);

const date = dayjs('2018-04-04T16:00:00.000Z');

// English locale
console.log(date.format('L')); // 04/04/2018
console.log(date.format('LL')); // April 4, 2018
console.log(date.format('LLL')); // April 4, 2018 4:00 PM
console.log(date.format('LLLL')); // Wednesday, April 4, 2018 4:00 PM
console.log(date.format('LT')); // 4:00 PM
console.log(date.format('LTS')); // 4:00:00 PM

// Different locale
const frenchDate = date.locale('fr');
console.log(frenchDate.format('LL')); // 4 avril 2018
console.log(frenchDate.format('LLLL')); // mercredi 4 avril 2018 16:00

Parsing Plugins

Custom Parse Format Plugin

Enables parsing dates with custom format strings.

/**
 * Parse date with custom format
 * @param dateString - Date string to parse
 * @param formatString - Format pattern
 * @param strict - Enable strict parsing mode
 * @returns Dayjs instance
 */
dayjs(dateString: string, formatString: string, strict?: boolean): Dayjs;

Usage Examples:

import customParseFormat from 'dayjs/plugin/customParseFormat';
dayjs.extend(customParseFormat);

// Parse with custom formats
const date1 = dayjs('12-25-1995', 'MM-DD-YYYY');
const date2 = dayjs('1995/25/12', 'YYYY/DD/MM');
const date3 = dayjs('1995-12-25 14:30', 'YYYY-MM-DD HH:mm');

// Strict parsing
const strict = dayjs('12-25-1995', 'MM-DD-YYYY', true);
const invalid = dayjs('invalid', 'MM-DD-YYYY', true);
console.log(invalid.isValid()); // false

// Array of formats
const flexible = dayjs('2018-05', ['YYYY', 'YYYY-MM', 'YYYY-MM-DD']);

Query Plugins

Additional query methods for date comparison and validation.

/**
 * Check if date is between two other dates
 * @param a - Start date
 * @param b - End date  
 * @param unit - Comparison unit
 * @param inclusivity - Include endpoints ('[]', '()', '[)', '(]')
 * @returns True if date is between the range
 */
isBetween(a: ConfigType, b: ConfigType, unit?: OpUnitType, inclusivity?: string): boolean;

/**
 * Check if date is same or after another date
 * @param date - Date to compare
 * @param unit - Comparison unit
 * @returns True if same or after
 */
isSameOrAfter(date: ConfigType, unit?: OpUnitType): boolean;

/**
 * Check if date is same or before another date
 * @param date - Date to compare
 * @param unit - Comparison unit
 * @returns True if same or before
 */
isSameOrBefore(date: ConfigType, unit?: OpUnitType): boolean;

/**
 * Check if date is today
 * @returns True if date is today
 */
isToday(): boolean;

/**
 * Check if date is tomorrow
 * @returns True if date is tomorrow
 */
isTomorrow(): boolean;

/**
 * Check if date is yesterday
 * @returns True if date is yesterday
 */
isYesterday(): boolean;

/**
 * Check if year is a leap year
 * @returns True if leap year
 */
isLeapYear(): boolean;

Usage Examples:

import isBetween from 'dayjs/plugin/isBetween';
import isSameOrAfter from 'dayjs/plugin/isSameOrAfter';
import isToday from 'dayjs/plugin/isToday';
import isLeapYear from 'dayjs/plugin/isLeapYear';

dayjs.extend(isBetween);
dayjs.extend(isSameOrAfter);
dayjs.extend(isToday);
dayjs.extend(isLeapYear);

const date = dayjs('2018-04-04');
const start = dayjs('2018-01-01');
const end = dayjs('2018-12-31');

// Between checks
console.log(date.isBetween(start, end)); // true
console.log(date.isBetween(start, end, 'day', '[]')); // inclusive
console.log(date.isBetween(start, end, 'day', '()')); // exclusive

// Same or comparisons
console.log(dayjs().isSameOrAfter(date)); // likely true
console.log(date.isSameOrBefore(dayjs())); // likely true

// Day checks
console.log(dayjs().isToday()); // true
console.log(dayjs().add(1, 'day').isTomorrow()); // true
console.log(dayjs().subtract(1, 'day').isYesterday()); // true

// Leap year
console.log(dayjs('2020-01-01').isLeapYear()); // true
console.log(dayjs('2021-01-01').isLeapYear()); // false

Plugin Installation Pattern

All plugins follow the same installation pattern:

Import the plugin function
Register it with dayjs.extend()
Use the new functionality

// Generic plugin installation pattern
import dayjs from 'dayjs';
import pluginName from 'dayjs/plugin/pluginName';

dayjs.extend(pluginName, optionalConfig);

// Plugin functionality is now available

Version

Tile

Files

plugins.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Plugins

Capabilities

Plugin System Core

Essential Plugins

UTC Plugin

Timezone Plugin

Duration Plugin

Relative Time Plugin

Formatting Plugins

Advanced Format Plugin

Localized Format Plugin

Parsing Plugins

Custom Parse Format Plugin

Query Plugins

Plugin Installation Pattern

plugins.mddocs/