How to format dates for different locales in TanStack Start v1

Problem

Dates do not have a universal display format. The sequence 10/12/2025 means October 12 in the United States but December 10 in the United Kingdom. Writing "Oct 12, 2025" assumes English month names and a specific ordering convention. Every region has its own expectations for date format, including the order of day, month, and year, the choice of separators, and whether month names are spelled out or abbreviated. When an application displays dates in a single fixed format, it feels foreign and confusing to users in most regions.

Users expect dates to appear in the format they learned and use daily. A date that looks natural to one audience can be ambiguous or jarring to another. Without locale-aware formatting, dates become a source of friction that undermines the user experience and makes the application feel less professional.

Solution

Format dates based on the user's locale by converting date values into strings that follow regional conventions for order, separators, and month names. React-intl provides formatting functions and components that use the browser's built-in internationalization APIs to apply the correct rules for each locale automatically. By passing a date value and optional formatting options to these tools, the application produces output that is both clear and natural for the user's language and region.

This approach ensures that dates are displayed correctly without manually implementing formatting logic for each locale. The formatting adapts to the user's locale, making dates immediately recognizable and reducing cognitive load.

Steps

1. Create a component that formats dates with the useIntl hook

Use the useIntl hook to access the formatDate method, which converts a date value into a locale-aware string.

import { useIntl } from "react-intl";

export function EventDate({ date }: { date: Date }) {
  const intl = useIntl();

  return (
    <time dateTime={date.toISOString()}>
      {intl.formatDate(date, {
        year: "numeric",
        month: "long",
        day: "numeric",
      })}
    </time>
  );
}

The formatDate method applies the locale's conventions for date display. The options object controls which parts of the date appear and their level of detail. The formatted string adapts to the locale provided by the IntlProvider higher in the component tree.

2. Format dates with specific styles using predefined options

Pass different option combinations to control the date format style, such as short numeric dates or long descriptive dates.

import { useIntl } from "react-intl";

export function ArticleMetadata({ publishedAt }: { publishedAt: Date }) {
  const intl = useIntl();

  const shortDate = intl.formatDate(publishedAt, {
    year: "numeric",
    month: "short",
    day: "numeric",
  });

  const longDate = intl.formatDate(publishedAt, {
    year: "numeric",
    month: "long",
    day: "numeric",
    weekday: "long",
  });

  return (
    <div>
      <p>Published: {shortDate}</p>
      <p>Full date: {longDate}</p>
    </div>
  );
}

The month option accepts values like numeric, 2-digit, short, long, and narrow. The weekday option adds the day of the week. Each locale interprets these options according to its own conventions, ensuring the output matches user expectations.

3. Use the FormattedDate component for declarative formatting

Render dates declaratively using the FormattedDate component, which accepts the same formatting options as the formatDate method.

import { FormattedDate } from "react-intl";

export function OrderSummary({ orderDate }: { orderDate: Date }) {
  return (
    <div>
      <h2>Order placed on</h2>
      <FormattedDate
        value={orderDate}
        year="numeric"
        month="long"
        day="numeric"
      />
    </div>
  );
}

The FormattedDate component renders the formatted date as a React fragment by default. It uses the locale from the IntlProvider context and applies the same formatting rules as the imperative API. This approach works well when the formatted date is the only content needed in that part of the component tree.

4. Format dates with time information

Include time components by adding hour and minute options to display both date and time in a single formatted string.

import { useIntl } from "react-intl";

export function AppointmentCard({ scheduledAt }: { scheduledAt: Date }) {
  const intl = useIntl();

  return (
    <div>
      <p>
        Scheduled for:{" "}
        {intl.formatDate(scheduledAt, {
          year: "numeric",
          month: "short",
          day: "numeric",
          hour: "numeric",
          minute: "2-digit",
        })}
      </p>
    </div>
  );
}

Adding hour and minute options produces a combined date and time string. The locale determines whether to use 12-hour or 24-hour time format and how to separate the date and time portions. This keeps the formatting consistent with regional expectations for displaying timestamps.