Tempo

https://tempo.formkit.com
Admin
Tempo is a lightweight JavaScript library for easy date and time manipulation, inspired by moment.js...
Tokens:12,184
Snippets:125
Trust Score:9.2
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Tempo via NPM

Source: https://tempo.formkit.com/

Use this command to add the Tempo library to your project dependencies.

```bash
npm i@formkit/tempo
```

--------------------------------

### yearStart(date)

Source: https://tempo.formkit.com/

Returns a new Date object with the date set to the start of the year.

```APIDOC
## function yearStart(date: string | Date): Date

### Description
Returns a new Date object with the date set to the start of the year.

### Parameters
- **date** (string | Date) - Required - The date to calculate from.
```

--------------------------------

### Get format token string

Source: https://tempo.formkit.com/

Retrieves the token format string for a specific style and locale.

```typescript
import { formatStr } from "@formkit/tempo"
formatStr("long", "en")
formatStr("long", "ja")
```

--------------------------------

### Get localized AM/PM string

Source: https://tempo.formkit.com/

Returns the localized string for AM or PM based on the provided locale.

```typescript
import { ap } from "@formkit/tempo"
ap("am", "ja")
```

--------------------------------

### dayOfYear(date)

Source: https://tempo.formkit.com/

Gets the day of the year a given date is.

```APIDOC
## function dayOfYear(date: Date): number

### Description
Gets the day of the year a given date is. For example, August 1st is the 213th day of the year on non-leap years and 214th on leap years.

### Parameters
- **date** (Date) - Required - The date to evaluate.
```

--------------------------------

### Format Time Styles

Source: https://tempo.formkit.com/

Demonstrates how to use time styles, including combining date and time properties and specifying locales.

```typescript
import { format } from "@formkit/tempo"
const date = "2010-06-09T15:32:00Z"
format(date, { time: "full" })
format(date, { time: "long" })
format(date, { time: "medium" })
format(date, { time: "short" })
// With a date style
format(date, { date: "full", time: "short" })
format(date, { date: "medium", time: "long" })
// With an explicit locale:
format(date, "full", "fr")
```

--------------------------------

### Format and Parse Dates with Tempo

Source: https://tempo.formkit.com/

Demonstrates basic date formatting and parsing using the Tempo library functions.

```javascript
import { format, parse } from "@formkit/tempo"
const readable = format(new Date(), "full")
parse(readable, "full")
```

--------------------------------

### Format Date Styles

Source: https://tempo.formkit.com/

Demonstrates how to use date styles with the format function, including shorthand and explicit locale usage.

```typescript
import { format } from "@formkit/tempo"
const date = new Date()
// These are the same:
format(date, "full")
format(date, { date: "full" })
format(date, "long")
format(date, "medium")
format(date, "short")
// With an explicit locale:
format(date, "full", "it")
```

--------------------------------

### weekStart(date, startOfWeekDay)

Source: https://tempo.formkit.com/

Returns a new Date object with the date set to the first day of the current week with the time set to 00:00:00 (local).

```APIDOC
## function weekStart(date: string | Date, startOfWeekDay: number): Date

### Description
Returns a new Date object with the date set to the first day of the current week with the time set to 00:00:00 (local).

### Parameters
- **date** (string | Date) - Required - The date to calculate from.
- **startOfWeekDay** (number) - Required - The day index (0-6, 0 is Sunday).
```

--------------------------------

### Format dates with tokens

Source: https://tempo.formkit.com/

Demonstrates various date formatting patterns using the format function and locale settings.

```typescript
import { format } from "@formkit/tempo"
// 👇 Try changing this to "fr"
const l = "en"
const t = new Date()
format(t, "YYYY-MM-DD", l)
format(t, "MMM D, YYYY", l)
format(t, "MMMM D, YYYY", l)
format(t, "DD/MM/YYYY", l)
format(t, "hh:mm:ss", l)
format(t, "h:mm:ss a", l)
format(t, "MMMM D, YYYY h:mm a", l)
format(t, "dddd, MMMM D, YYYY", l)
format(t, "M/D/YY", l)
format(t, "h:mm:ss A", l)
format(t, "YYYY-MM-DD HH:mm:ss", l)
format(t, "MMM D, YYYY HH:mm", l)
format(t, "dddd, MMMM D, YYYY h:mm:ss a", l)
format(t, "h:mm A", l)
format(t, "YYYY-MM-DDTHH:mm:ssZ", l)
format(t, "YY-M-D", l)
format(t, "YYYY/MM/DD", l)
format(t, "MMM D, YYYY HH:mm:ss", l)
format(t, "D MMMM YYYY", l)
format(t, "HH:mm", l)
format(t, "h:mm a Z", l)
format(t, "dddd, MMMM D, YYYY h:mm A", l)
format(t, "M/D/YYYY", l)
format(t, "hh:mm:ss a Z", l)
format(t, "YYYY-MM-DDTHH:mm:ss", l)
format(t, "MMM D, YYYY h:mm A", l)
format(t, "dddd, MMMM D, YYYY HH:mm:ss", l)
format(t, "h:mm:ss A Z", l)
format(t, "YY/MM/DD", l)
format(t, "YYYY MMMM D", l)
format(t, "M-D-YY", l)
format(t, "HH:mm:ss.SSS", l)
format(t, "YYYY-MM-DDTHH:mm:ss.SSSZ", l)
```

--------------------------------

### parts(format, locale)

Source: https://tempo.formkit.com/

Produces an array of 'parts' for a given format and locale, similar to Intl.DateTimeFormat.formatToParts() but supporting style and token formats.

```APIDOC
## parts(format, locale)

### Description
Produces an array of 'parts' for a given format and locale. It accepts style formats and token formats and returns parts with granular data such as the part’s token and a regex to match for it.

### Signature
`parts(format: string, locale: string): Part[]`

### Parameters
- **format** (string) - Required - The date format string or style object.
- **locale** (string) - Required - The locale string (e.g., 'en').

### Returns
- **Part[]** - An array of objects containing part details like token, pattern, and partName.
```

--------------------------------

### format(date, format, locale?)

Source: https://tempo.formkit.com/

Formats a date or ISO 8601 string into a localized string based on provided styles or tokens.

```APIDOC
## format(date, format, locale?)

### Description
Formats a given date or ISO 8601 string into a localized string. It supports both predefined format styles (via Intl.DateTimeFormat) and custom format tokens.

### Parameters
- **date** (Date | string) - Required - The date to format. Strings must be in ISO 8601 format.
- **format** (string | object) - Required - The format style (e.g., 'full', 'long', 'medium', 'short') or an object containing 'date' and/or 'time' properties.
- **locale** (string) - Optional - The BCP 47 language tag to use for localization.

### Usage Example
```javascript
import { format } from "@formkit/tempo";

// Using style strings
format(new Date(), "full");

// Using style objects
format(new Date(), { date: "full", time: "short" });

// With explicit locale
format(new Date(), "full", "it");
```
```

--------------------------------

### Handle milliseconds with SSS token

Source: https://tempo.formkit.com/

Shows how to format and parse milliseconds, including variable-length fractional seconds.

```typescript
import { format, parse } from "@formkit/tempo"
// Format with milliseconds using SSS token
const d = new Date("2024-01-15T10:30:45.789Z")
format({ date: d, format: "HH:mm:ss.SSS", tz: "UTC" })
format({ date: d, format: "YYYY-MM-DDTHH:mm:ss.SSSZ", tz: "UTC" })
// SSS always outputs 3 digits, padding with zeros
const d2 = new Date("2024-01-15T10:30:45.007Z")
format({ date: d2, format: "ss.SSS", tz: "UTC" })
// Parse milliseconds - SSS accepts variable-length input
parse("10:30:45.789", "HH:mm:ss.SSS")
// 1 digit -> 700ms
parse("10:30:45.7", "HH:mm:ss.SSS")
// 2 digits -> 780ms
parse("10:30:45.78", "HH:mm:ss.SSS")
// 6 digits -> 123ms (truncates to ms)
parse("10:30:45.123456", "HH:mm:ss.SSS")
```

--------------------------------

### parse(options)

Source: https://tempo.formkit.com/

Converts a date string into a Date object using a configuration object for advanced control.

```APIDOC
## function parse(options)

### Description
Converts a date string into a Date object using a ParseOptions configuration object.

### Parameters
- **options** (ParseOptions) - Required - Configuration object containing:
  - **date** (string) - Required - The date string.
  - **format** (Format) - Required - The format string or style object.
  - **locale** (string) - Required - The locale.
  - **partFilter** (function) - Optional - A function to filter out parts of the format.
  - **dateOverflow** ("forward" | "backward" | "throw") - Optional - Behavior when a date overflows a month (default: "backward").
```

--------------------------------

### format(options: FormatOptions)

Source: https://tempo.formkit.com/

Formats a date based on the provided options object.

```APIDOC
## format(options)

### Description
Formats a given date or ISO string according to specified format tokens or styles, with support for timezones, locales, and part filtering.

### Parameters
- **date** (string | Date) - Required - An ISO 8601 date string or a Date object.
- **format** (string | { date?: string, time?: string }) - Required - The format style or tokens to apply.
- **locale** (string) - Optional - The locale to use for formatting.
- **tz** (string) - Optional - The timezone to use for the date perspective.
- **genitive** (boolean) - Optional - Whether to use the genitive case for months and weekdays.
- **partFilter** (function) - Optional - A function that filters parts of the formatted date.

### Usage Example
```javascript
import { format } from "@formkit/tempo"

format({
  date: new Date(),
  format: "HH:mm",
  tz: "Africa/Johannesburg",
})
```
```

--------------------------------

### range(token, locale, genitive)

Source: https://tempo.formkit.com/

Returns an array of options for a given date token in a specified locale.

```APIDOC
## range(token, locale, genitive)

### Description
Returns an array of options for a given token in a given locale. For example, the token 'MMMM' in the locale 'en-US' would return an array of month names.

### Signature
`range(token: string, locale: string, genitive?: boolean): string[]`

### Parameters
- **token** (string) - Required - The date token (e.g., 'MMMM', 'dddd').
- **locale** (string) - Required - The locale string (default: 'en').
- **genitive** (boolean) - Optional - Whether to use genitive case (default: false).

### Returns
- **string[]** - An array of localized strings representing the options for the token.
```

--------------------------------

### date(date: string | Date): Date

Source: https://tempo.formkit.com/

Converts an ISO 8601 like string into a Date object. Partial ISO 8601 strings are accepted provided they contain at least a year and month.

```APIDOC
## date(date: string | Date)

### Description
Converts an ISO 8601 like string into a Date object. If a Date object is provided, it returns it as is.

### Parameters
- **date** (string | Date) - Required - The date string or object to convert.
```

--------------------------------

### format(date, format, locale)

Source: https://tempo.formkit.com/

Formats a Date object into a string based on the provided format tokens and locale.

```APIDOC
## format(date, format, locale)

### Description
Formats a date object into a string using specified tokens. The output respects the provided locale.

### Parameters
- **date** (Date) - Required - The date object to format.
- **format** (string) - Required - The format string containing tokens (e.g., "YYYY-MM-DD").
- **locale** (string) - Optional - The locale code (e.g., "en", "fr").

### Example
```javascript
import { format } from "@formkit/tempo";
format(new Date(), "YYYY-MM-DD", "en");
```
```

--------------------------------

### sameMinute

Source: https://tempo.formkit.com/

Checks if two dates are the same minute.

```APIDOC
## sameMinute(dateA, dateB)

### Description
Checks if two dates are the same minute. This function is useful for comparing dates but ignoring the seconds and milliseconds.

### Parameters
- **dateA** (Date) - Required
- **dateB** (Date) - Required

### Returns
- **boolean**
```

--------------------------------

### Generate date parts with Tempo

Source: https://tempo.formkit.com/

Produces an array of parts for a given format and locale, similar to Intl.DateTimeFormat.formatToParts().

```typescript
import { parts } from "@formkit/tempo"
parts("hh:mm a", "en")
parts({ date: "long" }, "en")
```

--------------------------------

### isAfter(inputDate, dateToCompare)

Source: https://tempo.formkit.com/

Returns true if the first date is after the second date, otherwise false.

```APIDOC
## isAfter(inputDate, dateToCompare)

### Parameters
- **inputDate** (string | Date) - Required
- **dateToCompare** (string | Date) - Required
```

--------------------------------

### isBefore

Source: https://tempo.formkit.com/

Returns true if the first date is before the second date, otherwise false.

```APIDOC
## isBefore(inputDate, dateToCompare)

### Description
Returns true if the first date is before the second date, otherwise false.

### Parameters
- **inputDate** (string | Date) - Required - The first date to compare.
- **dateToCompare** (string | Date) - Required - The second date to compare.

### Returns
- **boolean** - True if inputDate is before dateToCompare.
```

--------------------------------

### monthDays(date)

Source: https://tempo.formkit.com/

Returns the number of days in a given month.

```APIDOC
## function monthDays(date: Date): number

### Description
Returns the number of days in a given month.

### Parameters
- **date** (Date) - Required - The date to evaluate.
```

--------------------------------

### offset(date, tzA, tzB)

Source: https://tempo.formkit.com/

Returns the offset between two (IANA) timezones on a given date.

```APIDOC
## function offset(date: Date, tzA?: string, tzB?: string): string

### Description
Returns the offset between two (IANA) timezones on a given date. The results are ISO 8601 compatible string offsets like -0800 or +0530.

### Parameters
- **date** (Date) - Required - The date to calculate the offset for.
- **tzA** (string) - Optional - The first timezone (default: UTC).
- **tzB** (string) - Optional - The second timezone (default: browser).
```

--------------------------------

### formatStr(format, locale)

Source: https://tempo.formkit.com/

Returns the token format for a given format style.

```APIDOC
## function formatStr(format: { date?: string, time?: string }, locale?: string): string

### Description
Returns the token format for a given format style.

### Parameters
- **format** ({ date?: string, time?: string }) - Required - The format style object.
- **locale** (string) - Optional - The locale code.
```

--------------------------------

### ap(amOrPm, locale)

Source: https://tempo.formkit.com/

Returns either am or pm but in any given locale.

```APIDOC
## function ap(amOrPm: 'am' | 'pm', locale: string): string

### Description
Returns either am or pm but in any given locale.

### Parameters
- **amOrPm** ('am' | 'pm') - Required - The string to localize.
- **locale** (string) - Required - The locale code.
```

--------------------------------

### addDay(date, amount)

Source: https://tempo.formkit.com/

Returns a new Date object with a positive or negative number of days applied.

```APIDOC
## addDay(date, amount)

### Description
Returns a new Date object with a positive or negative number of days applied to the date argument.

### Parameters
- **date** (string | Date) - Required - The base date.
- **amount** (number) - Required - Number of days to add or subtract.
```

--------------------------------

### Retrieve locale-specific date ranges

Source: https://tempo.formkit.com/

Returns an array of options for a specific date token in a given locale.

```typescript
import { range } from "@formkit/tempo"
range("dddd", "en")
range("MMMM", "zh")
range("MMMM", "ar")
```

--------------------------------

### applyOffset(date, offset)

Source: https://tempo.formkit.com/

Returns a new Date object with a timezone offset applied.

```APIDOC
## applyOffset(date, offset)

### Description
Returns a new Date object with a timezone offset applied to the date argument.

### Parameters
- **date** (string | Date) - Required - The base date.
- **offset** (string) - Required - The offset string (e.g., +-HHmm).
```

--------------------------------

### parse(date, format, locale)

Source: https://tempo.formkit.com/

Converts a date string into a Date object using a specific format and locale.

```APIDOC
## function parse(date, format, locale)

### Description
Converts a date string into a JavaScript Date object. If parts of the date are missing, they default to the current date at midnight local time.

### Parameters
- **date** (string) - Required - The date string to parse.
- **format** (string | { date?: string, time?: string }) - Required - The format string or style object used to parse the date.
- **locale** (string) - Optional - The locale used to parse the date string.
```

--------------------------------

### Define FormatOptions Interface

Source: https://tempo.formkit.com/

The FormatOptions interface defines the structure for configuration objects passed to the format function.

```typescript
interface FormatOptions {  

/**
* An ISO 8601 date string or a Date object.
*/
date: string | Date, 
/**
* The format can be either format styles or format tokens.
*/
format: string | { date?: string, time?: string }, 
/**
* The locale to use when formatting.
*/
locale?: string, 
/**
* Converts the given date option to the timezone provided.
* For example, if the provided date option is 2021-01-01T00:00:00Z
* and the tz option is America/New_York and the format option is
* YYYY-MM-DD HH:mm:ss, the output will be 2020-12-31 19:00:00
*/
tz?: string, 
/**
* When true, the month and weekday names will be in the
* genitive case for locales where it is applicable.
*/
genitive?: boolean, 
/**
* A function that filters the parts of the formatted date.
* The function is called with each part of the formatted date
* and should return true to include the part in the output.
*/
partFilter?: (part: Part) => boolean
} 
```

--------------------------------

### tzDate(date: string | Date, tz: string): Date

Source: https://tempo.formkit.com/

Converts an ISO 8601 like string into a Date object with a specific IANA timezone applied.

```APIDOC
## tzDate(date: string | Date, tz: string)

### Description
Converts an ISO 8601 like string into a Date object with a timezone applied.

### Parameters
- **date** (string | Date) - Required - The date string or object.
- **tz** (string) - Required - The IANA timezone string (e.g., "America/Los_Angeles").
```

--------------------------------

### add(date, duration, dateOverflow)

Source: https://tempo.formkit.com/

Returns a new Date object with a duration object applied. To subtract time, use negative values.

```APIDOC
## add(date, duration, dateOverflow)

### Description
Returns a new Date object with a duration object applied. To subtract time, use negative values.

### Parameters
- **date** (string | Date | null) - Required - The base date.
- **duration** (Duration) - Required - Object containing years, months, weeks, days, hours, minutes, seconds, or milliseconds to add.
- **dateOverflow** (boolean) - Optional - Whether to allow month/year overflow (default: false).
```

--------------------------------

### addMonth(date, amount, dateOverflow)

Source: https://tempo.formkit.com/

Returns a new Date object with a positive or negative number of months applied.

```APIDOC
## addMonth(date, amount, dateOverflow)

### Description
Returns a new Date object with a positive or negative number of months applied to the date argument.

### Parameters
- **date** (string | Date) - Required - The base date.
- **amount** (number) - Required - Number of months to add or subtract.
- **dateOverflow** (boolean) - Required - Whether to allow overflow into the next month if the day does not exist.
```

--------------------------------

### Compare dates with isBefore

Source: https://tempo.formkit.com/

Determines if the first date occurs before the second date.

```typescript
import { isBefore } from "@formkit/tempo"
// Compare when the first date is before the second
isBefore("2013-03-15", "2013-03-16")
// Compare when the first date is after the second
isBefore("2013-03-17", "2013-03-16")
```

--------------------------------

### Parse ISO 8601 strings with date()

Source: https://tempo.formkit.com/

Converts ISO 8601 strings into Date objects. Partial strings are supported as long as they contain at least a year and month.

```typescript
import { date } from "@formkit/tempo"
// Partial ISO 8601 strings are acceptable
date("2013-11")
// Date at UTC
date("2013-11-18T12:00:00Z")
// Date with an offset (see tzDate() for timezones)
date("2013-11-18T12:00:00-0500")
```

--------------------------------

### addMinute(date, amount)

Source: https://tempo.formkit.com/

Returns a new Date object with a positive or negative number of minutes applied.

```APIDOC
## addMinute(date, amount)

### Description
Returns a new Date object with a positive or negative number of minutes applied to the date argument.

### Parameters
- **date** (string | Date) - Required - The base date.
- **amount** (number) - Required - Number of minutes to add or subtract.
```

--------------------------------

### iso8601(date)

Source: https://tempo.formkit.com/

Validates that a given date passes acceptable levels of ISO 8601 compatibility.

```APIDOC
## function iso8601(date: Date): boolean

### Description
Validates that a given date passes “acceptable” levels of ISO 8601 compatibility and can be utilized within Tempo. This allows incomplete dates but must include at least the year and month.

### Parameters
- **date** (Date) - Required - The date to validate.
```

--------------------------------

### Handling Date Overflows

Source: https://tempo.formkit.com/

Configure dateOverflow to control behavior when parsing invalid dates like February 30th.

```typescript
import { parse } from "@formkit/tempo"
// Nov 31 does not exist!
const date = "2011-11-31"
// Default overflow is "backward"
parse(date, "YYYY-MM-DD", "en-US")
// Parse "forward" into December
parse({
date,
format: "YYYY-MM-DD",
locale: "en-US",
dateOverflow: "forward",
})
```

```typescript
import { parse } from "@formkit/tempo"
// Nov 31 does not exist!
const date = "2011-11-31"
// Overflows can throw an error
parse({
date,
format: "YYYY-MM-DD",
locale: "en-US",
dateOverflow: "throw",
})
```

--------------------------------

### sameDay

Source: https://tempo.formkit.com/

Checks if two dates are the same day.

```APIDOC
## sameDay(dateA, dateB)

### Description
Checks if two dates are the same day. This function is useful for comparing dates but ignoring the time.

### Parameters
- **dateA** (Date) - Required
- **dateB** (Date) - Required

### Returns
- **boolean**
```

--------------------------------

### addYear(date, amount, dateOverflow)

Source: https://tempo.formkit.com/

Returns a new Date object with a positive or negative number of years applied.

```APIDOC
## addYear(date, amount, dateOverflow)

### Description
Returns a new Date object with a positive or negative number of years applied to the date argument.

### Parameters
- **date** (string | Date) - Required - The base date.
- **amount** (number) - Required - Number of years to add or subtract.
- **dateOverflow** (boolean) - Required - Whether to allow overflow into the next month if the day does not exist.
```

--------------------------------

### sameSecond

Source: https://tempo.formkit.com/

Checks if two dates are the same second.

```APIDOC
## sameSecond(dateA, dateB)

### Description
Checks if two dates are the same second. This function is useful for comparing dates but ignoring the milliseconds.

### Parameters
- **dateA** (Date) - Required
- **dateB** (Date) - Required

### Returns
- **boolean**
```

--------------------------------

### diffMinutes(dateA, dateB, roundingMethod)

Source: https://tempo.formkit.com/

Returns the number of minutes difference between two date objects with optional rounding.

```APIDOC
## diffMinutes(dateA, dateB, roundingMethod)

### Parameters
- **dateA** (string | Date) - Required
- **dateB** (string | Date) - Required
- **roundingMethod** ("trunc" | "round" | "floor" | "ceil") - Optional - Controls rounding for partial minutes.
```

--------------------------------

### Parsing Date Strings with Tempo

Source: https://tempo.formkit.com/

Basic usage of the parse function to convert various date string formats into Date objects.

```typescript
import { parse, format } from "@formkit/tempo"
// ISO 8601 is the default format
parse("1987-12-17")
// Sample date formats
parse("March 7, 1999", "MMMM D, YYYY", "en-US")
parse("12/17/1929", "MM/DD/YYYY")
parse("09-11-2049", "DD-MM-YYYY")
parse("Feb 11, 2011", "MMM D, YYYY")
parse("5 September 1987", "D MMMM YYYY")
parse("1982-05-17T07:44:00+0000", "YYYY-MM-DDTHH:mm:ssZ")
parse("23/08/1994 07:44 PM", "DD/MM/YYYY hh:mm A")
parse("1964-01-12 19:44:00", "YYYY-MM-DD HH:mm:ss")
parse("04/27/1942 07:44:00 PM", "MM/DD/YYYY hh:mm:ss A")
// Parse only time
parse("07:44", "HH:mm")
// Time parsed as utc
parse("07:44 -0000", "HH:mm ZZ")
const str = "Thursday, December 17, 1987"
parse(str, "full", "en-US")
const today = format(new Date(), { time: "short", date: "long" })
parse(today, { time: "short", date: "long" }, "en-US")
```

--------------------------------

### parse(dateString, format)

Source: https://tempo.formkit.com/

Parses a date string into a Date object based on the provided format pattern.

```APIDOC
## parse(dateString, format)

### Description
Parses a string representation of a date into a Date object. The `SSS` token supports variable-length fractional seconds.

### Parameters
- **dateString** (string) - Required - The string to parse.
- **format** (string) - Required - The format pattern to match against.

### Example
```javascript
import { parse } from "@formkit/tempo";
parse("10:30:45.789", "HH:mm:ss.SSS");
```
```

--------------------------------

### diffMonths(dateA, dateB, roundingMethod)

Source: https://tempo.formkit.com/

Returns the number of months difference between two date objects with optional rounding.

```APIDOC
## diffMonths(dateA, dateB, roundingMethod)

### Parameters
- **dateA** (string | Date) - Required
- **dateB** (string | Date) - Required
- **roundingMethod** ("trunc" | "round" | "floor" | "ceil") - Optional - Controls rounding for partial months.
```

--------------------------------

### yearEnd(date)

Source: https://tempo.formkit.com/

Returns a new Date object with the date set to the end of the year.

```APIDOC
## function yearEnd(date: string | Date): Date

### Description
Returns a new Date object with the date set to the end of the year.

### Parameters
- **date** (string | Date) - Required - The date to calculate from.
```

--------------------------------

### Compare Dates with isAfter

Source: https://tempo.formkit.com/

Checks if the first date occurs after the second date.

```typescript
import { isAfter } from "@formkit/tempo"
// Compare when the first date is before the second
isAfter("2013-03-15", "2013-03-16")
// Compare when the first date is after the second
isAfter("2013-03-17", "2013-03-16")
```

--------------------------------

### Format Dates with Timezones

Source: https://tempo.formkit.com/

Use the tz option to format dates relative to a specific timezone.

```javascript
import { format } from "@formkit/tempo"
format({
date: new Date(),
format: "HH:mm",
tz: "Africa/Johannesburg",
})
format({
date: new Date(),
format: { time: "short" },
tz: "America/Los_Angeles",
})
format({
date: "1999-12-31T20:00Z",
format: "YYYY-MM-DD HH:mm",
tz: "Pacific/Chatham",
})
```

--------------------------------

### setMonth(date: string | Date | null, month: number, dateOverflow: boolean): Date

Source: https://tempo.formkit.com/

Returns a new Date object with the zero-based month set.

```APIDOC
## setMonth(date: string | Date | null, month: number, dateOverflow: boolean)

### Description
Returns a new Date object with the zero-based month set. By default, invalid days clamp to the last day of the target month; set dateOverflow to true to allow overflow.

### Parameters
- **date** (string | Date | null) - Required - The base date.
- **month** (number) - Required - The zero-based month (0-11).
- **dateOverflow** (boolean) - Optional - Whether to allow date overflow (default: false).
```

--------------------------------

### Apply Genitive Case for Locales

Source: https://tempo.formkit.com/

Enable the genitive option to use the genitive case for month and weekday names in supported locales.

```javascript
import { format } from "@formkit/tempo"
const t = "2013-03-15"
// The month name
format({ date: t, format: "MMMM", locale: "ru" })
// The genitive form of the month name
format({
date: t,
format: "MMMM",
locale: "ru",
genitive: true,
})
```

--------------------------------

### Calculate Day Differences with diffDays

Source: https://tempo.formkit.com/

Computes the difference in days between two dates, with optional rounding methods.

```typescript
import { diffDays } from "@formkit/tempo"
diffDays("2021-07-03", "2021-01-01")
// lets round the difference
diffDays("2025-02-07T18:31:00Z", "2025-02-05T05:31:00Z", "round")
```

--------------------------------

### diff(dateA, dateB, options)

Source: https://tempo.formkit.com/

Calculates the difference between two dates and returns a Duration object containing years, months, weeks, days, hours, minutes, seconds, and milliseconds.

```APIDOC
## diff(dateA, dateB, options)

### Description
Returns the difference between two dates as a duration object. The result can be used for further date calculations or formatting.

### Parameters
- **dateA** (string | Date | null) - Required - The first date.
- **dateB** (string | Date) - Required - The second date.
- **options** (DiffOptions) - Optional - Configuration object containing `abs` (boolean) to return absolute values and `skip` (Array/Set) to omit specific units.
```

--------------------------------

### yearDays(date)

Source: https://tempo.formkit.com/

Calculates the number of days in the year of the provided date.

```APIDOC
## yearDays(date)

### Description
Returns the number of days in a given year. Accounts for leap years and century years.

### Signature
`yearDays(date: Date): number`

### Parameters
- **date** (Date) - Required - The date object to extract the year from.

### Returns
- **number** - The total number of days in that year.
```

--------------------------------

### diffDays(dateA, dateB, roundingMethod)

Source: https://tempo.formkit.com/

Returns the number of days difference between two date objects with optional rounding.

```APIDOC
## diffDays(dateA, dateB, roundingMethod)

### Parameters
- **dateA** (string | Date) - Required
- **dateB** (string | Date) - Required
- **roundingMethod** ("trunc" | "round" | "floor" | "ceil") - Optional - Controls rounding for partial days.
```

--------------------------------

### Format dates in specific timezones

Source: https://tempo.formkit.com/

Pass the tz option to the format function to display a date according to a specific region's timezone.

```javascript
import { format } from "@formkit/tempo"
const date = new Date()
// Time in New York?
format({
date,
format: "hh:mm a",
tz: "America/New_York",
})
// Time in Tokyo?
format({
date,
format: "hh:mm a",
tz: "Asia/Tokyo",
})
```

--------------------------------

### isEqual

Source: https://tempo.formkit.com/

Returns true if the first date is equal to the second date, otherwise false.

```APIDOC
## isEqual(dateLeft, dateRight)

### Description
Returns true if the first date is equal to the second date, otherwise false.

### Parameters
- **dateLeft** (string | Date) - Required - The first date to compare.
- **dateRight** (string | Date) - Required - The second date to compare.

### Returns
- **boolean** - True if dates are equal.
```

--------------------------------

### addHour(date, amount)

Source: https://tempo.formkit.com/

Returns a new Date object with a positive or negative number of hours applied.

```APIDOC
## addHour(date, amount)

### Description
Returns a new Date object with a positive or negative number of hours applied to the date argument.

### Parameters
- **date** (string | Date) - Required - The base date.
- **amount** (number) - Required - Number of hours to add or subtract.
```

--------------------------------

### Compare dates with isEqual

Source: https://tempo.formkit.com/

Determines if two dates are identical.

```typescript
import { isEqual } from "@formkit/tempo"
// Compare when the first date is before the second
isEqual("2013-03-15", "2013-03-16")
// Compare when the first date is equal with the second
isEqual("2013-03-16", "2013-03-16")
```

--------------------------------

### Apply timezones with tzDate()

Source: https://tempo.formkit.com/

Converts a date string into a Date object adjusted for a specific IANA timezone.

```typescript
import { tzDate } from "@formkit/tempo"
// Produces the date for 12 noon Nov 18, 2013 in New York
tzDate("2013-11-18 12:00", "America/New_York")
```

--------------------------------

### sameYear

Source: https://tempo.formkit.com/

Checks if two dates are the same year.

```APIDOC
## sameYear(dateA, dateB)

### Description
Checks if two dates are the same year. This function is useful for comparing dates but ignoring the month, day, and time.

### Parameters
- **dateA** (Date) - Required
- **dateB** (Date) - Required

### Returns
- **boolean**
```

--------------------------------

### sameHour

Source: https://tempo.formkit.com/

Checks if two dates are the same hour.

```APIDOC
## sameHour(dateA, dateB)

### Description
Checks if two dates are the same hour. This function is useful for comparing dates but ignoring the minutes, seconds, and milliseconds.

### Parameters
- **dateA** (Date) - Required
- **dateB** (Date) - Required

### Returns
- **boolean**
```

--------------------------------

### addSecond(date, amount)

Source: https://tempo.formkit.com/

Returns a new Date object with a positive or negative number of seconds applied.

```APIDOC
## addSecond(date, amount)

### Description
Returns a new Date object with a positive or negative number of seconds applied to the date argument.

### Parameters
- **date** (string | Date) - Required - The base date.
- **amount** (number) - Required - Number of seconds to add or subtract.
```

--------------------------------

### nearestDay(date, searchFunction, constraint)

Source: https://tempo.formkit.com/

Performs a bidirectional search for the nearest date that passes a given search function.

```APIDOC
## function nearestDay(date: Date, searchFunction: (date: Date) => boolean, constraint: number | "month" | "week" | "year"): Date | null

### Description
Performs a bidirectional search for the nearest date that passes a given search function. It stops searching when it finds a result or when it reaches the constraint bounds.

### Parameters
- **date** (Date) - Required - The starting date.
- **searchFunction** ((date: Date) => boolean) - Required - The function to test dates against.
- **constraint** (number | "month" | "week" | "year") - Optional - The search bounds.
```

--------------------------------

### diffWeeks(dateA, dateB, roundingMethod)

Source: https://tempo.formkit.com/

Returns the number of weeks difference between two date objects with optional rounding.

```APIDOC
## diffWeeks(dateA, dateB, roundingMethod)

### Parameters
- **dateA** (string | Date) - Required
- **dateB** (string | Date) - Required
- **roundingMethod** ("trunc" | "round" | "floor" | "ceil") - Optional - Controls rounding for partial weeks.
```

--------------------------------

### Calculate timezone offsets

Source: https://tempo.formkit.com/

Use the offset function to determine the difference between two timezones, supporting historical sub-minute offsets.

```javascript
import { offset } from "@formkit/tempo"
const date = new Date()
// Your browser’s offset to UTC
offset(date)
// Your browser’s offset to Hawaii
offset(date, "Pacific/Honolulu")
// Your Hawaii’s offset to UTC
offset(date, "UTC", "Pacific/Honolulu")
// The offset from London to New York today
offset(date, "Europe/London", "America/New_York")
// The offset from Moscow to Kolkata, India
offset(date, "Europe/Moscow", "Asia/Kolkata")
// 👀 Dates matter due to DST:
offset("2023-10-25", "Europe/London", "America/New_York")
offset("2023-10-30", "Europe/London", "America/New_York")
```

--------------------------------

### Parse date string into parts

Source: https://tempo.formkit.com/

Extracts values from a date string based on a provided structure of parts.

```typescript
import { parts, parseParts } from "@formkit/tempo"
const dateStr = "2021-01-01"
const format = "YYYY-MM-DD"
const locale = "en-US"
const formatParts = parts(format, locale)
parseParts(dateStr, formatParts)
```

--------------------------------

### addMillisecond(date, amount)

Source: https://tempo.formkit.com/

Returns a new Date object with a positive or negative number of milliseconds applied.

```APIDOC
## addMillisecond(date, amount)

### Description
Returns a new Date object with a positive or negative number of milliseconds applied to the date argument.

### Parameters
- **date** (string | Date) - Required - The base date.
- **amount** (number) - Required - Number of milliseconds to add or subtract.
```

--------------------------------

### Calculate Date Differences with diff

Source: https://tempo.formkit.com/

Calculates the duration between two dates, supporting unit skipping and integration with add functions.

```typescript
import { add, diff } from "@formkit/tempo"
// Get a duration object
diff("2025-04-01 12:00:50", "2024-01-01 12:00:00")
// Skip units you do not want in the result
diff("2025-07-01 12:01:00", "2024-01-01 12:00:00", {
skip: ["years", "minutes"],
})
// Apply a duration to another date
add("2024-01-30", diff("2024-03-01", "2024-01-30"))
```

--------------------------------

### parseParts(dateString, parts)

Source: https://tempo.formkit.com/

Extracts values from a date string based on provided parts.

```APIDOC
## function parseParts(dateString: string, parts: Part[]): FilledPart[]

### Description
Given a date string and the parts, this function returns the parts with the appropriate values extracted from the date string and added to a value property.

### Parameters
- **dateString** (string) - Required - The date string to parse.
- **parts** (Part[]) - Required - The parts definition.
```

--------------------------------

### diffSeconds(dateA, dateB, roundingMethod)

Source: https://tempo.formkit.com/

Returns the number of seconds difference between two date objects with optional rounding.

```APIDOC
## diffSeconds(dateA, dateB, roundingMethod)

### Parameters
- **dateA** (string | Date) - Required
- **dateB** (string | Date) - Required
- **roundingMethod** ("trunc" | "round" | "floor" | "ceil") - Optional - Controls rounding for partial seconds.
```

--------------------------------

### fourDigitYear(year)

Source: https://tempo.formkit.com/

Converts a 2 digit year into a 4 digit year.

```APIDOC
## function fourDigitYear(year: string): number

### Description
Converts a 2 digit year into a 4 digit year. This function assumes years 20 years into the future belong to the current century, and the past 80 are in the past century.

### Parameters
- **year** (string) - Required - The 2-digit year string.
```

--------------------------------

### Add days to a date

Source: https://tempo.formkit.com/

Returns a new Date object with a specified number of days added or subtracted.

```typescript
import { addDay } from "@formkit/tempo"
// Add 1 day
addDay("2013-03-15")
// Add 5 days
addDay("2013-03-15", 5)
// Subtract 3 days
addDay("2013-03-15", -3)
```

--------------------------------

### diffYears(dateA, dateB, roundingMethod)

Source: https://tempo.formkit.com/

Returns the number of years difference between two date objects with optional rounding.

```APIDOC
## diffYears(dateA, dateB, roundingMethod)

### Parameters
- **dateA** (string | Date) - Required
- **dateB** (string | Date) - Required
- **roundingMethod** ("trunc" | "round" | "floor" | "ceil") - Optional - Controls rounding for partial years.
```

--------------------------------

### sameMillisecond

Source: https://tempo.formkit.com/

Checks if two dates have the same millisecond value (0-999).

```APIDOC
## sameMillisecond(dateA, dateB)

### Description
Checks if two dates have the same millisecond value (0-999). This compares only the millisecond component, ignoring the rest of the timestamp.

### Parameters
- **dateA** (Date) - Required
- **dateB** (Date) - Required

### Returns
- **boolean**
```

--------------------------------

### diffMilliseconds(dateA, dateB)

Source: https://tempo.formkit.com/

Returns the number of milliseconds difference between two date objects.

```APIDOC
## diffMilliseconds(dateA, dateB)

### Description
Calculates the total difference in milliseconds between two dates.

### Parameters
- **dateA** (string | Date) - Required
- **dateB** (string | Date) - Required
```

--------------------------------

### Apply timezone offset to a date

Source: https://tempo.formkit.com/

Applies a specific timezone offset string to a date. Useful for timezone-aware date manipulation.

```typescript
import { offset, applyOffset, date } from "@formkit/tempo"
// 💡 Pickup at 9:30 in Europe/Lisbon
// Notice that the time has no offset, thus it is "local":
const d = "2025-03-25 09:30"
// local time:
console.log(new Date(d).toISOString())
// Lisbon is at UTC+0:
const lisbonOffset = offset(d, "Europe/Lisbon")
// Apply the offset to the time:
applyOffset(d, lisbonOffset)
```

--------------------------------

### diffHours(dateA, dateB, roundingMethod)

Source: https://tempo.formkit.com/

Returns the number of hours difference between two date objects with optional rounding.

```APIDOC
## diffHours(dateA, dateB, roundingMethod)

### Parameters
- **dateA** (string | Date) - Required
- **dateB** (string | Date) - Required
- **roundingMethod** ("trunc" | "round" | "floor" | "ceil") - Optional - Controls rounding for partial hours.
```

--------------------------------

### Filter Date Parts

Source: https://tempo.formkit.com/

The partFilter option allows selective removal of specific date components from the final string.

```javascript
import { format, tzDate, weekEnd } from "@formkit/tempo"
// "full" time normally looks like:
// `10:51:29 PM -0500`
// We can selectively remove the offset:
format({
date: new Date(),
format: { time: "full" },
partFilter: (part) => {
// Remove the offset
return part.partName !== "timeZoneName"
},
})
```

--------------------------------

### Filtering Date Parts

Source: https://tempo.formkit.com/

Use partFilter to selectively include or exclude specific components of a date string during parsing.

```typescript
import { parse } from "@formkit/tempo"
parse({
date: "1999-09-02",
format: "YYYY-MM-DD",
locale: "en",
// Remove day info:
partFilter: (part) => part.partName !== "day",
})
parse({
date: "1:12:00 PM -0400",
format: { time: "full" },
locale: "en-US",
// Remove TZ info:
partFilter: (part) => part.partName !== "timeZoneName",
})
```

--------------------------------

### Remove timezone offsets

Source: https://tempo.formkit.com/

Use removeOffset to adjust a Date object so its internal methods return the time as it appears in the target timezone.

```javascript
import { format, offset, removeOffset } from "@formkit/tempo"
// rendered at:
const d = new Date()
// local time:
format(d, "HH:mm")
const offsetToBerlin = offset(d, "Europe/Berlin")
const adjusted = removeOffset(d, offsetToBerlin)
// The time in Berlin
format(adjusted, "HH:mm")
```
Tokens:
Raw