Fumanchu Fumanchu

Date Helpers

Handlebars provides a comprehensive set of built-in helpers for working with dates. These helpers are used to format, manipulate, and compare dates, making it easier to display and work with date information.

Table of Contents

Date Helpers

Fumanchu provides powerful date manipulation capabilities using dayjs and chrono-node for natural language date parsing.

{{year}}

Get the current year as a string.

Example

{{year}}

{{date}}

Format a date with support for human-readable date strings, Date objects, timestamps, or defaults to current date.

Parameters:

  • dateInput (optional): Date string, Date object, timestamp, or undefined (defaults to now)
  • format (optional): Format string (defaults to "YYYY-MM-DD")

Supported format tokens:

  • YYYY or yyyy: 4-digit year
  • YY or yy: 2-digit year
  • MM or mm: Month (01-12)
  • DD or dd: Day of month (01-31)
  • HH or hh: Hour (00-23)
  • mm: Minute (00-59)
  • ss: Second (00-59)

Examples

{{date "January 15, 2023" "YYYY-MM-DD"}}


{{date "5 years ago" "YYYY"}}


{{date "next Friday" "MM/DD/YYYY"}}


{{date}}


{{date "2023-01-15" "dd/mm/yyyy"}}

{{moment}}

Legacy alias for {{date}}. Works exactly the same as the date helper.

Example

{{moment "December 25, 2023" "YYYY-MM-DD"}}

Current Time Helpers

{{timestamp}}

Returns the current Unix timestamp in milliseconds.

Example

{{timestamp}}

{{now}}

Returns the current date/time with optional formatting.

Parameters:

  • format (optional): Format string (defaults to "YYYY-MM-DD HH:mm:ss")

Examples

{{now}}


{{now "YYYY-MM-DD"}}


{{now "HH:mm:ss"}}

Relative Time Helpers

{{fromNow}}

Display relative time from now (e.g., "5 minutes ago", "in 2 hours").

Parameters:

  • dateInput: Date string, Date object, or timestamp

Examples

{{fromNow "2 days ago"}}


{{fromNow "tomorrow"}}


{{fromNow "January 1, 2025"}}

{{ago}}

Alias for {{fromNow}}. Shows how long ago a date was.

Example

{{ago "5 minutes ago"}}

{{toNow}}

Opposite of fromNow. Shows relative time to now (less commonly used).

Example

{{toNow "2 hours ago"}}

Date Arithmetic Helpers

{{dateAdd}}

Add time to a date.

Parameters:

  • dateInput (optional): Date to add to (defaults to now)
  • amount: Number to add
  • unit: Unit of time ("year", "month", "week", "day", "hour", "minute", "second")

Examples

{{dateAdd "2023-01-15" 5 "days"}}


{{dateAdd "2023-01-15" 2 "months"}}


{{dateAdd undefined 1 "year"}}

{{dateSubtract}}

Subtract time from a date.

Parameters:

  • dateInput (optional): Date to subtract from (defaults to now)
  • amount: Number to subtract
  • unit: Unit of time

Examples

{{dateSubtract "2023-01-15" 5 "days"}}


{{dateSubtract "2023-01-15" 2 "weeks"}}

Date Period Helpers

{{startOf}}

Get the start of a time period.

Parameters:

  • dateInput (optional): Date (defaults to now)
  • unit: Unit of time ("year", "month", "week", "day", "hour", "minute", "second")

Examples

{{startOf "2023-01-15" "month"}}


{{startOf "2023-06-15" "year"}}


{{startOf "2023-01-15 14:30:45" "day"}}

{{endOf}}

Get the end of a time period.

Parameters:

  • dateInput (optional): Date (defaults to now)
  • unit: Unit of time

Examples

{{endOf "2023-01-15" "month"}}


{{endOf "2023-06-15" "year"}}

Date Comparison Helpers

{{isBefore}}

Check if the first date is before the second date.

Parameters:

  • date1: First date
  • date2: Second date

Returns: true or false

Example

{{#if (isBefore "2023-01-10" "2023-01-15")}}
  Date 1 is before Date 2
{{/if}}

{{isAfter}}

Check if the first date is after the second date.

Parameters:

  • date1: First date
  • date2: Second date

Returns: true or false

Example

{{#if (isAfter "2023-01-20" "2023-01-15")}}
  Date 1 is after Date 2
{{/if}}

{{isSame}}

Check if two dates are the same, with optional unit precision.

Parameters:

  • date1: First date
  • date2: Second date
  • unit (optional): Unit for comparison ("year", "month", "day", etc.)

Returns: true or false

Examples

{{#if (isSame "2023-01-15" "2023-01-15")}}
  Dates are the same
{{/if}}

{{#if (isSame "2023-01-15" "2023-12-31" "year")}}
  Same year
{{/if}}

{{isBetween}}

Check if a date is between two other dates (inclusive).

Parameters:

  • dateInput: Date to check
  • startDate: Start of range
  • endDate: End of range

Returns: true or false

Example

{{#if (isBetween "2023-01-15" "2023-01-10" "2023-01-20")}}
  Date is in range
{{/if}}

Date Utilities

{{diff}}

Calculate the difference between two dates.

Parameters:

  • date1: First date
  • date2: Second date
  • unit (optional): Unit for result ("year", "month", "day", "hour", etc.). Defaults to milliseconds.

Returns: Number

Examples

{{diff "2023-01-20" "2023-01-15" "days"}}


{{diff "2023-03-15" "2023-01-15" "months"}}


{{diff "2025-01-15" "2023-01-15" "years"}}

{{toISOString}}

Convert a date to ISO 8601 format.

Parameters:

  • dateInput: Date to convert

Examples

{{toISOString "2023-01-15"}}


{{toISOString "January 15, 2023"}}

Internationalization Helpers

{{dateTimezone}}

Format a date in a specific timezone.

Parameters:

  • dateInput: Date to format
  • timezone: IANA timezone string (e.g., "America/New_York", "UTC", "Europe/London")
  • format (optional): Format string (defaults to "YYYY-MM-DD HH:mm:ss")

Examples

{{dateTimezone "2023-01-15 12:00:00" "America/New_York" "YYYY-MM-DD HH:mm:ss"}}


{{dateTimezone "2023-01-15" "UTC"}}

{{dateLocale}}

Format a date with a specific locale.

Parameters:

  • dateInput: Date to format
  • locale: Locale code (e.g., "en", "fr", "de")
  • format (optional): Format string (defaults to "YYYY-MM-DD HH:mm:ss")

Example

{{dateLocale "2023-01-15" "en" "YYYY-MM-DD"}}

Natural Language Date Parsing

All date helpers support natural language date parsing powered by chrono-node:

  • "today", "tomorrow", "yesterday"
  • "next Friday", "last Monday"
  • "5 days ago", "in 2 weeks"
  • "January 15, 2023"
  • "2023-01-15"
  • Date objects
  • Unix timestamps

Examples

{{date "tomorrow" "YYYY-MM-DD"}}
{{date "next Friday" "MM/DD/YYYY"}}
{{date "5 years ago" "YYYY"}}
{{fromNow "2 hours ago"}}
{{dateAdd "next week" 3 "days"}}