or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

calendar.mdcomponents.mddate-creation.mdformatting.mdindex.mdlocalization.mdmanipulation.mdvalidation-comparison.md
tile.json

formatting.mddocs/

Date Formatting and Display

This capability provides comprehensive date formatting functionality with predefined format keys and custom format strings, supporting localized output and user-friendly display helpers.

Predefined Format Keys

format(date: Moment, formatKey: keyof DateIOFormats): string

Formats a date using predefined format keys that provide consistent, locale-aware formatting across the application.

Parameters:

  • date - Moment object to format
  • formatKey - Predefined format key from DateIOFormats interface

Returns: Formatted date string

Usage:

const date = utils.parseISO("2023-10-30T14:30:45.123Z");

// Common format keys
const full = utils.format(date, "fullDate"); // "Oct 30, 2023"
const fullWithWeekday = utils.format(date, "fullDateWithWeekday"); // "Monday, Oct 30, 2023"
const short = utils.format(date, "shortDate"); // "10/30/2023"
const year = utils.format(date, "year"); // "2023"
const month = utils.format(date, "month"); // "October"
const monthShort = utils.format(date, "monthShort"); // "Oct"

// Time formats
const fullTime = utils.format(date, "fullTime"); // "2:30:45 PM"
const fullTime24h = utils.format(date, "fullTime24h"); // "14:30:45"
const hours12h = utils.format(date, "hours12h"); // "2 PM"
const hours24h = utils.format(date, "hours24h"); // "14"

// Combined formats
const fullDateTime = utils.format(date, "fullDateTime"); // "Oct 30, 2023 2:30 PM"
const fullDateTime24h = utils.format(date, "fullDateTime24h"); // "Oct 30, 2023 14:30"

// Specialized formats
const keyboardDate = utils.format(date, "keyboardDate"); // "10/30/2023"
const monthAndYear = utils.format(date, "monthAndYear"); // "October 2023"
const weekday = utils.format(date, "weekday"); // "Monday"
const weekdayShort = utils.format(date, "weekdayShort"); // "Mon"

Custom Format Strings

formatByString(date: Moment, formatString: string): string

Formats a date using custom Moment.js format strings for maximum flexibility.

Parameters:

  • date - Moment object to format
  • formatString - Custom format string using Moment.js tokens

Returns: Formatted date string

Usage:

const date = utils.parseISO("2023-10-30T14:30:45.123Z");

// Custom date formats
const custom1 = utils.formatByString(date, "YYYY-MM-DD"); // "2023-10-30"
const custom2 = utils.formatByString(date, "DD/MM/YYYY"); // "30/10/2023"
const custom3 = utils.formatByString(date, "MMM Do, YYYY"); // "Oct 30th, 2023"
const custom4 = utils.formatByString(date, "dddd, MMMM Do YYYY"); // "Monday, October 30th 2023"

// Custom time formats
const time1 = utils.formatByString(date, "HH:mm:ss"); // "14:30:45"
const time2 = utils.formatByString(date, "h:mm A"); // "2:30 PM"
const time3 = utils.formatByString(date, "HH:mm"); // "14:30"

// Combined custom formats
const datetime1 = utils.formatByString(date, "YYYY-MM-DD HH:mm:ss"); // "2023-10-30 14:30:45"
const datetime2 = utils.formatByString(date, "MMM DD, YYYY [at] h:mm A"); // "Oct 30, 2023 at 2:30 PM"

// Advanced formatting with milliseconds and timezone
const precise = utils.formatByString(date, "YYYY-MM-DD HH:mm:ss.SSS"); // "2023-10-30 14:30:45.123"
const withTz = utils.formatByString(date, "YYYY-MM-DD HH:mm:ss Z"); // "2023-10-30 14:30:45 +00:00"

Number Formatting

formatNumber(numberToFormat: string): string

Formats number strings according to locale conventions. This is a pass-through for Moment.js, primarily used for consistency with other date-io adapters.

Parameters:

  • numberToFormat - String representation of number to format

Returns: Formatted number string (typically unchanged in Moment.js implementation)

Usage:

const formatted = utils.formatNumber("1234"); // "1234"
const decimal = utils.formatNumber("12.34"); // "12.34"

Format Helper Text

getFormatHelperText(format: string): string

Returns user-friendly helper text describing what a format string will produce, useful for showing users examples of expected input formats.

Parameters:

  • format - Format string to generate helper text for

Returns: Human-readable description of the format

Usage:

const helper1 = utils.getFormatHelperText("YYYY-MM-DD"); // "yyyy-mm-dd"
const helper2 = utils.getFormatHelperText("DD/MM/YYYY"); // "dd/mm/yyyy"
const helper3 = utils.getFormatHelperText("MM/DD/YYYY HH:mm"); // "mm/dd/yyyy hh:mm"

// Use in form placeholders or help text
const placeholder = `Enter date (${utils.getFormatHelperText("YYYY-MM-DD")})`;

Available Format Keys

The DateIOFormats interface provides the following predefined format keys:

interface DateIOFormats {
  // Date formats
  fullDate: string; // Full date: "Oct 30, 2023"
  fullDateWithWeekday: string; // With weekday: "Monday, Oct 30, 2023"
  normalDate: string; // Normal format
  normalDateWithWeekday: string; // Normal with weekday
  shortDate: string; // Short: "10/30/2023"
  
  // Component formats
  year: string; // "2023"
  month: string; // "October"
  monthShort: string; // "Oct"
  monthAndYear: string; // "October 2023"
  monthAndDate: string; // "October 30"
  weekday: string; // "Monday"
  weekdayShort: string; // "Mon"
  dayOfMonth: string; // "30"
  
  // Time formats
  hours12h: string; // "2 PM"
  hours24h: string; // "14"
  minutes: string; // "30"
  seconds: string; // "45"
  fullTime: string; // "2:30:45 PM"
  fullTime12h: string; // "2:30:45 PM"
  fullTime24h: string; // "14:30:45"
  
  // Combined formats
  fullDateTime: string; // "Oct 30, 2023 2:30 PM"
  fullDateTime12h: string; // "Oct 30, 2023 2:30:45 PM"
  fullDateTime24h: string; // "Oct 30, 2023 14:30:45"
  
  // Input formats
  keyboardDate: string; // "10/30/2023"
  keyboardDateTime: string; // "10/30/2023 2:30 PM"
  keyboardDateTime12h: string; // "10/30/2023 2:30:45 PM"
  keyboardDateTime24h: string; // "10/30/2023 14:30:45"
}

Locale-Aware Formatting

All formatting methods respect the locale specified during MomentUtils initialization:

// English formatting (default)
const enUtils = new MomentUtils({ locale: "en" });
const date = enUtils.parseISO("2023-10-30T14:30:00.000Z");
const enFormatted = enUtils.format(date, "fullDate"); // "Oct 30, 2023"

// French formatting
const frUtils = new MomentUtils({ locale: "fr" });
const frFormatted = frUtils.format(date, "fullDate"); // "30 oct. 2023"

// German formatting
const deUtils = new MomentUtils({ locale: "de" });
const deFormatted = deUtils.format(date, "fullDate"); // "30. Okt. 2023"

// Custom format with locale
const frCustom = frUtils.formatByString(date, "dddd, MMMM Do YYYY"); // "lundi, octobre 30e 2023"

Custom Format Override

You can override default formats when creating a MomentUtils instance:

const customUtils = new MomentUtils({
  locale: "en",
  formats: {
    fullDate: "YYYY-MM-DD", // Override default fullDate format
    shortDate: "MM/DD/YY", // Override default shortDate format
    fullTime: "HH:mm:ss" // Override to 24-hour format
  }
});

const date = customUtils.parseISO("2023-10-30T14:30:45.000Z");
const customFormatted = customUtils.format(date, "fullDate"); // "2023-10-30" (instead of "Oct 30, 2023")