Lime Web Components API Documentation - v6.24.0
    Preparing search index...

    Interface DateTimeFormatter

    Service for formatting and parsing date and time values according to user locale

    The DateTimeFormatter provides locale-aware formatting for dates and times, ensuring that dates are displayed in a format familiar to the user. It handles various date types including full timestamps, date-only values, times, and relative dates (like "2 hours ago").

    The service also handles the complexities of parsing date strings and converting between UTC and local time, which is particularly important for date-only values that need timezone compensation.

    const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
    const timestamp = '2024-03-15T14:30:00.000Z';
    const formatted = formatter.format(timestamp, 'datetime');
    // Result: "2024-03-15 14:30" (format varies by locale)

    const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
    const now = new Date();

    formatter.format(now, 'datetime');  // "2024-03-15 14:30"
    formatter.format(now, 'date');      // "2024-03-15"
    formatter.format(now, 'time');      // "14:30" or "2:30 PM"
    formatter.format(now, 'relative');  // "2 hours ago"
    interface DateTimeFormatter {
        format(
            date: string | Date,
            options: DateTimeType | DateTimeFormatterOptions,
        ): string;
        parse(date: string | Date, type: DateTimeType): Date;
    }
    Index

    Methods

    format parse

    Methods

    • Format a date or timestamp as a localized string

      Converts a date value to a human-readable string according to the user's locale and the specified format type. The formatting automatically respects the user's locale preferences for date ordering, separators, and time format.

      Parameters

      Returns string

      A localized string representation of the date

      const date = new Date('2024-03-15T14:30:00');

      formatter.format(date, 'date');     // "2024-03-15" or "15/03/2024" depending on locale
      formatter.format(date, 'time');     // "14:30" or "2:30 PM" depending on locale
      formatter.format(date, 'datetime'); // "2024-03-15 14:30"
      formatter.format(date, 'relative'); // "2 hours ago"

      const date = new Date();

      // With specific hour cycle
      const formatted = formatter.format(date, {
          type: 'datetime',
          hourCycle: 'h23' // Force 24-hour format
      });

      // Date string from API will be automatically parsed
      const apiDate = "2024-03-15T14:30:00.000Z";
      const display = formatter.format(apiDate, 'datetime');

      If a string is supplied to the date parameter, it will be converted to a Date object before formatting. See DateTimeFormatter.parse for details on how strings are parsed.

    • Parse a date string and convert it to a Date object with proper timezone handling

      This method handles the complexity of converting date strings to Date objects, with special handling for date-only values that need timezone compensation. This is important when working with dates stored in a database, which are typically in UTC but should be displayed in the user's local timezone.

      For date-only types ('date', 'year', 'quarter', 'month', 'week'), the method compensates for timezone differences to ensure the date is displayed as stored.

      Parameters

      • date: string | Date

        The date value to parse. Can be a Date object (returned unchanged) or a string in ISO format

      • type: DateTimeType

        The date type, which determines how timezone conversion is handled

      Returns Date

      A Date object in local time

      // Database stores "2024-03-15" as "2024-03-15T00:00:00.000Z"
      const dbValue = '2024-03-15T00:00:00.000Z';
      const localDate = formatter.parse(dbValue, 'date');
      // localDate represents 2024-03-15 in local time, regardless of timezone

      // Datetime values include time and respect timezones
      const timestamp = '2024-03-15T14:30:00.000Z';
      const localTime = formatter.parse(timestamp, 'datetime');
      // localTime is converted to user's timezone

      // Date strings without timezone are interpreted as local time
      const localDateStr = '2024-03-15 23:59:59';
      const date = formatter.parse(localDateStr, 'datetime');

    Settings

    Member Visibility

    On This Page

    Methods