Cómo formatear cantidades de moneda en TanStack Start v1

Problema

Los precios combinan dos desafíos de localización: la representación de la moneda y el formato de números. El mismo valor monetario aparece como $1,200.50 en Estados Unidos y 1 200,50 € en Alemania. El símbolo de la moneda se mueve, los separadores decimales y de agrupación se intercambian, e incluso el espaciado cambia.

Estas convenciones no son preferencias sino expectativas. Mostrar precios en un formato no familiar hace que los usuarios cuestionen si están viendo la cantidad correcta. Un precio mostrado como "1200.50 EUR" a un usuario alemán o "1.200,50$" a un usuario estadounidense crea fricción y erosiona la confianza.

Solución

Formatear los valores monetarios basándose tanto en la moneda como en la configuración regional del usuario. Esto combina la ubicación del símbolo de la moneda con las reglas de formato de números específicas de la configuración regional, creando precios que coinciden con las expectativas regionales sobre cómo debe verse el dinero.

Utiliza el método formatNumber de react-intl con la opción style: 'currency' para aplicar tanto el código de moneda como las convenciones de formato de la configuración regional del usuario. La API Intl.NumberFormat del navegador maneja automáticamente la ubicación del símbolo, la elección del separador y el espaciado.

Pasos

1. Crear un componente de formato de moneda

Construye un componente reutilizable que acepte un valor numérico y un código de moneda, y luego formatee el precio utilizando la configuración regional del usuario.

import { useIntl } from "react-intl";

interface PriceProps {
  value: number;
  currency: string;
}

export function Price({ value, currency }: PriceProps) {
  const intl = useIntl();

  const formattedPrice = intl.formatNumber(value, {
    style: "currency",
    currency: currency,
  });

  return <span>{formattedPrice}</span>;
}

El hook useIntl proporciona acceso a la API de formateo. El método formatNumber con style: 'currency' aplica tanto el símbolo de la moneda como el formato de números específico de la configuración regional.

2. Usa el componente con diferentes monedas

Muestra precios en toda tu aplicación pasando el monto numérico y el código de moneda.

export default function ProductCard() {
  return (
    <div>
      <h2>Premium Plan</h2>
      <Price value={1200.5} currency="USD" />
    </div>
  );
}

El componente formatea automáticamente el precio según la configuración regional del usuario. Un usuario de EE.UU. ve "$1,200.50" mientras que un usuario alemán ve "1.200,50 $".

3. Formatea precios con precisión decimal personalizada

Controla el número de decimales mostrados añadiendo las opciones minimumFractionDigits y maximumFractionDigits.

export function PriceWithPrecision({ value, currency }: PriceProps) {
  const intl = useIntl();

  const formattedPrice = intl.formatNumber(value, {
    style: "currency",
    currency: currency,
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  });

  return <span>{formattedPrice}</span>;
}

Esto asegura una visualización decimal consistente en todos los precios, incluso cuando el valor es un número entero como 100.

4. Crea un helper para formateo en línea

Para casos donde un componente envolvente es innecesario, crea una función helper de formateo.

import { useIntl } from "react-intl";

export function useFormatCurrency() {
  const intl = useIntl();

  return (value: number, currency: string) => {
    return intl.formatNumber(value, {
      style: "currency",
      currency: currency,
    });
  };
}

Utiliza este hook cuando necesites precios formateados en atributos, valores calculados u otros contextos que no sean JSX.

export function CheckoutSummary({ total }: { total: number }) {
  const formatCurrency = useFormatCurrency();

  return (
    <button aria-label={`Pay ${formatCurrency(total, "USD")}`}>Checkout</button>
  );
}

El helper devuelve una cadena de texto simple adecuada para cualquier contexto donde no se puedan usar componentes JSX.