Como adicionar espaços ou vírgulas ao formatar números em JavaScript: guia completo

Como adicionar vírgulas ao formatar números em JavaScript? Guia detalhado

Você já se perguntou por que 1000000 é difícil de ler, enquanto 1.000.000 é instantâneo? O olho humano simplesmente não foi feito para longas sequências de dígitos. Os separadores de milhares (vírgulas, espaços ou pontos) não são apenas uma questão de estética, mas de usabilidade e percepção da informação.

Se você programa em JavaScript e trabalha com preços, estatísticas, IDs ou qualquer dado numérico, mais cedo ou mais tarde surgirá a pergunta: "Como formatar um número, adicionando vírgulas ou espaços entre as casas dos milhares?". No Stack Overflow, essa pergunta já teve milhares de visualizações — o que significa que preocupa muitos.

Neste artigo, não vamos apenas fornecer o código pronto. Vamos analisar três formas principais: desde a API moderna integrada até as expressões regulares clássicas. Você aprenderá como fazer o JavaScript "falar" a linguagem dos números legíveis. Vamos lá!

Por que um número simples é um problema?

Imagine que você exibe no site: Preço: 1234567.89 R$. O olho tropeça. Quanto é isso? Um milhão? Doze milhões? E se adicionarmos vírgulas: 1.234.567,89 — fica claro imediatamente: pouco mais de um milhão.

Em JavaScript, um número é apenas um Number. Ele não tem um "formato de exibição" embutido. Tudo o que vemos é o resultado da conversão para string. E é aí que entramos nós, desenvolvedores.

Método 1: toLocaleString() — o rei da simplicidade

A forma mais elegante e moderna é usar o método toLocaleString(). Ele está disponível em qualquer número em JavaScript e leva em conta a localidade do usuário.

const number = 1234567.89;\nconst formatted = number.toLocaleString('pt-BR');\nconsole.log(formatted); // "1.234.567,89"\n

Observe: para a localidade brasileira (pt-BR), o separador de milhares é o ponto e o separador decimal é a vírgula. Para a americana (en-US), são a vírgula e o ponto:

console.log(number.toLocaleString('en-US')); // "1,234,567.89"\n

Vantagens:

\n
• Mínimo de código.
\n
• Respeita os padrões locais (espaços, pontos, vírgulas).
\n
• Funciona em todos os navegadores modernos e Node.js.
\n

Desvantagens:

\n
• Menos controle sobre o formato (não é possível simplesmente substituir o ponto por vírgula sem manipulações adicionais).
\n
• Navegadores antigos (IE11) podem não suportar o segundo argumento (locales).
\n

Método 2: Intl.NumberFormat — flexibilidade e potência

Se você precisa de controle total, use o objeto Intl.NumberFormat. É o mesmo mecanismo do toLocaleString(), mas com configurações estendidas.

const formatter = new Intl.NumberFormat('pt-BR', {\n    style: 'decimal',\n    useGrouping: true, // Ativa os separadores de milhares\n    minimumFractionDigits: 2,\n    maximumFractionDigits: 2\n});\n\nconsole.log(formatter.format(1234567.8)); // "1.234.567,80"\n

Quer moeda? Fácil:

const currencyFormatter = new Intl.NumberFormat('pt-BR', {\n    style: 'currency',\n    currency: 'USD',\n    minimumFractionDigits: 0\n});\nconsole.log(currencyFormatter.format(1000000)); // "US$ 1.000.000"\n

Dá para mudar o separador de milhares manualmente? Não há uma opção direta, mas você pode usar replace:

let result = formatter.format(1234567.89);\nresult = result.replace(/\\./g, ','); // Substitui pontos por vírgulas\nconsole.log(result); // "1,234,567,80"\n

Vantagens:

\n
• Máxima flexibilidade (moeda, porcentagens, unidades de medida).
\n
• Performance (pode ser criado uma vez e reutilizado).
\n

Desvantagens:

\n
• Um pouco mais de código que toLocaleString().
\n
• Ainda depende da localidade.
\n