Utility Functions

React Calendar DateTime Picker provides a comprehensive set of utility functions for date manipulation, comparison, and formatting. All utilities work with both Gregorian and Jalali calendar systems.

Utilities

The library exports various utility functions for date manipulation and formatting:

Date Conversion

gregorianToJalali(date: Day): Day - Convert Gregorian to Jalali date
jalaliToGregorian(date: Day): Day - Convert Jalali to Gregorian date
getToday(locale?: CalendarLocale): Day - Get today's date

Date Comparison

isBefore(date: Day, compareDate: Day, locale?: CalendarLocale): boolean
isAfter(date: Day, compareDate: Day, locale?: CalendarLocale): boolean
isSameDay(date: Day, compareDate: Day, locale?: CalendarLocale): boolean
isSameMonth(date: Day, compareDate: Day): boolean
isSameYear(date: Day, compareDate: Day): boolean
isLeapYear(year: number, locale?: CalendarLocale): boolean
isBetween(date: Day, startDate: Day, endDate: Day, locale?: CalendarLocale): boolean

Date Manipulation

addDays(date: Day, days: number, locale?: CalendarLocale): Day
addMonths(date: Day, months: number, locale?: CalendarLocale): Day
addYears(date: Day, years: number, locale?: CalendarLocale): Day
subtractDays(date: Day, days: number, locale?: CalendarLocale): Day
subtractMonths(date: Day, months: number, locale?: CalendarLocale): Day
subtractYears(date: Day, years: number, locale?: CalendarLocale): Day

Formatting

formatDateForInput(date: Day | null, format?: string): string
dayToString(date: Day, divider?: string): string
parseAndValidateDate(dateString: string, calendarSystem: CalendarLocale, dateFormat?: string): ValidationResult<Day> - Parse and validate date string. Without dateFormat, accepts YYYY/MM/DD format with /, -, or . separators. With dateFormat parameter, parses according to the format pattern. The separator is automatically extracted from the format (e.g., "DD/MM/YYYY" for "25/12/2024", "MM-DD-YYYY" for "12-25-2024", "DD+MM+YYYY" for "25+12+2024").
toPersianNumeral(num: number): string

Interactive Examples: Select a date in the calendar below to see how the utility functions work with real data.

Interactive Demo

Select a date in the calendar below to see utility function results in real-time. All examples on this page use the date you select here.

💡 Tip: Select a date in the calendar to see all utility functions in action.

Select a Date

Selected Date

No date selected. Please select a date in the calendar.

Date Comparison

Functions for comparing dates, checking relationships, and determining date positions.

Basic Comparisons

isBefore

isBefore(date1, date2, locale?)

Returns true if date1 is before date2

Select a date to see the result

isAfter

isAfter(date1, date2, locale?)

Returns true if date1 is after date2

Select a date to see the result

isSameDay

isSameDay(date1, date2, locale?)

Returns true if both dates represent the same day

Select a date to see the result

isSameMonth

isSameMonth(date1, date2)

Returns true if both dates are in the same month and year

Select a date to see the result

isSameYear

isSameYear(date1, date2)

Returns true if both dates are in the same year

Select a date to see the result

isLeapYear

isLeapYear(year, locale?)

Returns true if the given year is a leap year in the specified calendar system

Select a date to see the result

Range Checking

isBetween

isBetween(date, startDate, endDate, locale?)

Returns true if date falls between startDate and endDate (inclusive)

Select a date to see the result

Date Manipulation

Functions for adding/subtracting time periods and calculating differences.

Adding Time Periods

addDays

addDays(date, days, locale?)

Adds the specified number of days to the given date

Select a date to see the result

addMonths

addMonths(date, months, locale?)

Adds the specified number of months to the given date

Select a date to see the result

addYears

addYears(date, years, locale?)

Adds the specified number of years to the given date

Select a date to see the result

getDifferenceInDays

getDifferenceInDays(date1, date2, locale?)

Calculates the number of days between two dates. Returns a positive number if date1 is after date2, negative if date1 is before date2, or 0 if they're the same day.

Select a date to see the result

Calendar Conversion

Convert dates between Gregorian and Jalali calendar systems.

convertToJalali

convertToJalali(gregorianDate)

Convert Gregorian date to Jalali (Persian)

Select a date to see the result

convertToGregorian

convertToGregorian(jalaliDate)

Convert Jalali date to Gregorian

Select a date to see the result

Date Boundaries

These functions return boundary dates for a given time period. They help you get the first or last day of a day, month, or year. Useful for date range queries, filtering, and calculations.

Example: If you have a date like `December 15, 2024`, `startOfMonth` returns `December 1, 2024` (first day of that month), and `endOfMonth` returns `December 31, 2024` (last day of that month).

startOfDay

startOfDay(date)

Returns the same date but at the start of the day (00:00:00). Useful for date range queries where you want to include the entire day.

Select a date to see the result

endOfDay

endOfDay(date)

Returns the same date but at the end of the day (23:59:59). Useful for inclusive date range queries.

Select a date to see the result

startOfMonth

startOfMonth(date, locale?)

Returns the first day of the month for the given date. Example: startOfMonth(December 15, 2024) returns December 1, 2024.

Select a date to see the result

endOfMonth

endOfMonth(date, locale?)

Returns the last day of the month for the given date. Example: endOfMonth(December 15, 2024) returns December 31, 2024.

Select a date to see the result

startOfYear

startOfYear(date)

Returns the first day of the year for the given date. Example: startOfYear(December 15, 2024) returns January 1, 2024.

Select a date to see the result

endOfYear

endOfYear(date, locale?)

Returns the last day of the year for the given date. Example: endOfYear(December 15, 2024) returns December 31, 2024.

Select a date to see the result

getStartOfWeek

getStartOfWeek(date, weekStart, locale?)

Returns the first day of the week for the given date. weekStart is 0-6 (0 = Sunday, 1 = Monday, ..., 6 = Saturday).

Select a date to see the result

getEndOfWeek

getEndOfWeek(date, weekStart, locale?)

Returns the last day of the week for the given date. weekStart is 0-6 (0 = Sunday, 1 = Monday, ..., 6 = Saturday).

Select a date to see the result

Range Utilities

Functions for working with date ranges, getting all days in a range, and range operations.

getDaysInRange

getDaysInRange(range, locale?)

Returns an array of all days in the given date range (inclusive). Useful for iterating over all dates in a range.

Select a date to see the result

Usage Examples

Common patterns and real-world usage examples.

Date Range Validation

import { isBefore, isAfter, addDays } from 'react-calendar-datetime-picker'

function validateBookingDates(checkIn, checkOut) {
  const today = getToday('gregorian')
  const maxStay = addDays(checkIn, 30, 'gregorian')

  // Check-in must be today or later
  if (isBefore(checkIn, today, 'gregorian')) {
    return 'Check-in date cannot be in the past'
  }

  // Check-out must be after check-in
  if (!isAfter(checkOut, checkIn, 'gregorian')) {
    return 'Check-out must be after check-in'
  }

  // Maximum stay is 30 days
  if (isAfter(checkOut, maxStay, 'gregorian')) {
    return 'Maximum stay is 30 days'
  }

  return null // Valid
}

Calendar Conversion

import { convertToJalali, convertToGregorian, dayToString } from 'react-calendar-datetime-picker'

// Gregorian to Jalali
const gregorianDate = { year: 2024, month: 12, day: 25 }
const jalaliDate = convertToJalali(gregorianDate)
console.log(dayToString(jalaliDate, '/')) // "1403/10/5"

// Jalali to Gregorian
const persianDate = { year: 1403, month: 10, day: 5 }
const gregorian = convertToGregorian(persianDate)
console.log(dayToString(gregorian, '/')) // "2024/12/25"

Age Calculation

import { getDifferenceInYears, getToday } from 'react-calendar-datetime-picker'

function calculateAge(birthDate) {
  const today = getToday('gregorian')
  return getDifferenceInYears(today, birthDate, 'gregorian')
}

// Usage
const birthDate = { year: 1990, month: 5, day: 15 }
const age = calculateAge(birthDate)
console.log(`Age: ${age}`) // "Age: 34"

Function Reference

Complete list of all available utility functions.

Function	Parameters	Returns	Description
`isBefore`	`date1, date2, locale?`	`boolean`	Check if date1 is before date2
`isAfter`	`date1, date2, locale?`	`boolean`	Check if date1 is after date2
`isSameDay`	`date1, date2, locale?`	`boolean`	Check if dates are the same day
`isBetween`	`date, start, end, locale?`	`boolean`	Check if date is between start and end
`addDays`	`date, days, locale?`	`Day`	Add days to date
`addMonths`	`date, months, locale?`	`Day`	Add months to date
`addYears`	`date, years, locale?`	`Day`	Add years to date
`getDifferenceInDays`	`date1, date2, locale?`	`number`	Returns number of days between date1 and date2. Positive if date1 is after date2, negative if before, 0 if same day.
`convertToJalali`	`gregorianDate`	`Day`	Convert Gregorian to Jalali
`convertToGregorian`	`jalaliDate`	`Day`	Convert Jalali to Gregorian
`startOfDay`	`date`	`Day`	Get start of day
`endOfDay`	`date`	`Day`	Get end of day
`startOfMonth`	`date, locale?`	`Day`	Get start of month
`endOfMonth`	`date, locale?`	`Day`	Get end of month
`startOfYear`	`date`	`Day`	Get start of year
`endOfYear`	`date, locale?`	`Day`	Get end of year
`isSameMonth`	`date1, date2`	`boolean`	Check if dates are in the same month and year
`isSameYear`	`date1, date2`	`boolean`	Check if dates are in the same year
`isLeapYear`	`year, locale?`	`boolean`	Check if a year is a leap year in the specified calendar system
`getStartOfWeek`	`date, weekStart, locale?`	`Day`	Get start of week (weekStart: 0-6, 0=Sunday)
`getEndOfWeek`	`date, weekStart, locale?`	`Day`	Get end of week (weekStart: 0-6, 0=Sunday)
`getDaysInRange`	`Range, locale?`	`Day[]`	Get all days in a date range (inclusive)
`dayToString`	`date, divider?`	`string`	Convert Day object to string format
`parseAndValidateDate`	`dateString: string` `calendarSystem: CalendarLocale` `dateFormat: string?`	`ValidationResult<Day>`	Parse and validate a date string. Without `dateFormat`, accepts YYYY/MM/DD format with /, -, or . separators. With `dateFormat`, parses according to the pattern (separator auto-extracted). Also validates year is within calendar range.