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.
The date to format, either as a Date object or an ISO string
Either a string specifying the format type (e.g., 'date', 'time', 'relative'), or a DateTimeFormatterOptions object for more control
A localized string representation of the date
import { PlatformServiceName } from '@limetech/lime-web-components';
const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
const date = new Date();
// The output depends on the user's locale and hour cycle, so the same date
// looks different for different users.
const dateAndTime = formatter.format(date, 'time');
const clockTime = formatter.format(date, 'timeofday');
const dateOnly = formatter.format(date, 'date');
const month = formatter.format(date, 'month');
const quarter = formatter.format(date, 'quarter');
const year = formatter.format(date, 'year');
const week = formatter.format(date, 'week');
const relative = formatter.format(date, 'relative');
import { PlatformServiceName } from '@limetech/lime-web-components';
const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
const formatted = formatter.format(new Date(), {
type: 'time',
hourCycle: 'h23',
});
import { PlatformServiceName } from '@limetech/lime-web-components';
const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
const repository = platform.get(PlatformServiceName.LimeObjectRepository);
if (context.limetype && context.id) {
const object = await repository.loadObject(context.limetype, context.id, {
properties: ['createdtime'],
});
if (object) {
const createdTime = object.getValue('createdtime');
const formatted = formatter.format(createdTime, 'time');
}
}
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.
The date value to parse. Can be a Date object (returned unchanged) or a string in ISO format
The date type, which determines how timezone conversion is handled
A Date object in local time
import { PlatformServiceName } from '@limetech/lime-web-components';
const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
// The server stores a `date` as midnight UTC. Parsing it as `date` keeps the
// same calendar day in local time, so a user west of UTC does not see the day
// before.
const storedDate = '2024-03-15T00:00:00.000Z';
const localDate = formatter.parse(storedDate, 'date');
import { PlatformServiceName } from '@limetech/lime-web-components';
const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
// A `time` value points at one moment, so it is not shifted. The `Date` shows
// that moment in the user's own time zone.
const storedTimestamp = '2024-03-15T14:30:00.000Z';
const localTime = formatter.parse(storedTimestamp, 'time');
import { PlatformServiceName } from '@limetech/lime-web-components';
const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
// Without a time zone offset the string is read as local time, not as UTC.
const localDateString = '2024-03-15 23:59:59';
const date = formatter.parse(localDateString, 'time');
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.
Example: Basic date formatting