useFormattedDate hook

The useFormattedDate hook provides a way for frontend developers to format dates and times as strings, rather than JSX elements. This is useful when you need an ink formatted date to use in places where react elements are not accepted.

While the FormattedDate component renders as a React element, useFormattedDate returns a formatting function that outputs a string. Both use the same underlying logic and support the same formats, but serve different use cases.

useFormattedDate is intended for internal Carta developers who want to format dates into user-friendly strings, with support for time zones and locale-aware formatting. Internally, useFormattedDate works exactly like FormattedDate, ensuring consistency across the product.

If you have additional questions or encounter issues, please reach out on the #ink channel.

The useFormattedDate hook supports multiple ISO 8601 formats as well as Date instances, moment objects, and a few legacy formats. If an unsupported value is provided, the hook will simply return an empty string.

When no date or time is provided, the hook defaults to first day of the month and the start of the day in UTC (i.e., 12:00 AM). The same happens when only a year is provided, defaulting to January 1st of that year.

useFormattedDate accepts up to 9 digits of fractional seconds in ISO-8601 input strings (e.g., 2025-12-31T12:00:00.123456789Z), in line with the full ISO 8601 specification.

However, it is important to note the following:

At present, you cannot override the default locale or input timezone settings. All configuration is handled internally to promote consistency with FormattedDate.

The user's local timezone is determined by their browser or system settings and based on the Intl.DateTimeFormat().resolvedOptions().timeZone method, which is widely supported in modern browsers.

You can update displayTimezone (and other options) per invocation of formatDate, but there is no way to configure persistent defaults at the hook level. Each call to formatDate requires all relevant options to be specified.

Future enhancements will allow setting user preferences or defaults when initializing the hook, reducing the need to pass options every time.

For now, all dates are formatted using the en-US locale, except for the i18n formats, which use en-GB. In the future the component will be expanded to allow developers to customize the locale and timezone settings.

useFormattedDate will return an object containing the formatDate function that can be used to format dates.

formatDate requires a config object as argument to work, the parameters it needs are:

formatDate will return an object containing the formatted date string and an optional __meta field for debugging purposes.

import { useFormattedDate } from "@carta/ink";

const { formatDate } = useFormattedDate();

const result = formatDate({
  value: "2025-12-31T12:00:00Z",
  format: "condensedWithTime",
});

console.log(result.value);
// Dec 31, 2025, 7:00 AM EST (if user is in New York)
// Dec 31, 2025, 12:00 PM UTC (if user is in London)

import { useFormattedDate } from "@carta/ink";

const { formatDate } = useFormattedDate();

const result = formatDate({
  value: "2025-12-31T12:00:00Z",
  format: "condensedWithTime",
  displayTimezone: "America/New_York",
});

console.log(result.value); // Dec 31, 2025, 7:00 AM EST

interface UseFormattedDateOptionsType {
  value: Date | Moment | string;
  format?: FormatOptions; // e.g. 'condensedWithTime', 'long', 'short', etc.
  displayTimezone?: string; // IANA timezone, e.g. 'America/New_York'
  enableDebug?: boolean; // If true, returns extra metadata
}

interface UseFormattedDateResultType {
  value: string; // The formatted date string
  __meta?: any; // Optional metadata for debugging
  isoDate?: string; // ISO representation of the parsed date
}

If you encounter unexpected results or need to troubleshoot date parsing and formatting, you can enable debugging by passing enableDebug: true to formatDate. This will include a __meta field in the result object, containing detailed information about the parsing process, detected errors, and the type of input.

import { useFormattedDate } from "@carta/ink";

const { formatDate } = useFormattedDate();
const result = formatDate({
  value: "2024-99-99", // Invalid date
  format: "condensedWithTime",
  enableDebug: true,
});

console.log(result.__meta);
// {
//   dateTime: {
//     errors: { month: 'Invalid month', day: 'Invalid day' },
//     parsingType: 'ISO Date'
//   }
// }

If your input is not in a supported format (see Core Concepts), useFormattedDate will return an empty string. Only ISO-8601, Date objects, moment objects, and select legacy formats are supported.

If you do not specify a displayTimezone, the date is formatted in the user's local timezone, which may vary based on their browser or system settings.

Not yet. All options must be provided per invocation of formatDate. Future releases may allow persistent defaults at the hook level.

Yes, use the FormattedDate component for UI rendering.