Como usar bandeiras com nomes de países em projetos web
O assunto bandeiras com nomes de paises aparece com frequência em projetos que precisam de seletor de idioma, formulário de endereço ou listagem internacional. A ideia básica é ter o ícone da bandeira junto ao nome do país para evitar ambiguidade. Não tem segredo, mas existem detalhes que quem não pratica isso no dia a dia costuma ignorar. Existem três abordagens principais para incluir essas bandeiras no seu projeto. A primeira é usar uma biblioteca pronta, como FlagKit, flag-icon-css ou a API flagcdn. A segunda é baixar pacotes de SVGs prontos e hospedá-los no seu próprio servidor. A terceira, menos recomendada, é usar imagens rasterizadas da Wikipédia com licença GNU FDL, o que costuma causar problemas de cache e direitos.
A biblioteca flag-icon-css ainda é a mais usada no ecossistema open source. Ela funciona com classes CSS e um arquivo de fontes ou sprites. A versão mais recente cobre cerca de 250 códigos ISO 3166-1, incluindo territórios dependentes. Se você precisa apenas de bandeiras padrão, ela resolve em minutos. A desvantagem é que o bundle completo pesa cerca de 800KB gzipped se você importar tudo. O ideal é configurar o webpack ou Vite para carregar apenas os ícones que o projeto realmente usa.
bandeiras com nomes de paises na prática
No meu caso, precisei implementar um seletor de país em um formulário de checkout que atendia a clientes do Mercosul e também de países africanos de língua portuguesa. O problema que encontrei não era a ausência de bandeiras. Era a consistência visual entre versões diferentes das mesmas bandeiras. O Brasil, por exemplo, tem uma variante usada pelo governo e uma versão mais antiga que ainda aparece em algumas bases de dados. A API flagcdn usa a versão vigente, mas a flag-icon-css, dependendo da versão, pode entregar uma bandeira com o losango amarelo levemente deslocado em relação ao padrão oficial. O workaround que usei foi simples. Em vez de depender da biblioteca para o Brasil, Angola, Moçambique e Portugal, baixe os SVGs oficiais do site do governo brasileiro e dos institutos cartográficos de cada país e sobreescrevi os arquivos no repositório. Usei um script Node que converte os SVGs para WebP e gera um mapa de bits otimizado. O processo todo leva uns dez minutos e garante que as cores estejam corretas em telas Retina.
Uma coisa que poucos mencionam é o problema do SSR. Se você renderiza as bandeiras no servidor com Next.js ou Nuxt, o CSS da biblioteca de ícones precisa estar disponível no client também. Caso contrário, a bandeira aparece como um quadrado vazio até o.hydrate completar. A solução mais limpa é carregar a folha de estilos de forma dinâmica com next/dynamic ou usar o approach de inline SVG, que elimina a dependência de CSS externo completamente. Para quem trabalha com dados internacionais, vale saber que a ISO 3166-1 alpha-2 tem algumas entradas que geram confusão. O código "TL" para Timor-Leste às vezes é trocado por "TP", que é a designação antiga. A bandeira correspondente ao código antigo simplesmente não existe em bibliotecas modernas. Se você migrou um banco de dados legado, pode encontrar bandeiras quebradas sem motivo aparente. A correção é mapear manualmente os códigos obsoletos antes de exibir.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Outro ponto que causa dor de cabeça é o dimensionamento. Bandeira em 16px fica ilegível em alguns casos. A bandeira do Paraguai, por exemplo, tem três faixas horizontais com símbolos no centro. Em tamanhos pequenos, o escudo central some e a bandeira parece uma simples listra tricolor. Para resolutions abaixo de 24px, prefira bandeiras com designs geométricos simples, como as do Japão ou da Polônia. Para tamanhos maiores, o detalhe dos escudos e estrelas aparece corretamente. Se o projeto exige alta acessibilidade, considere adicionar aria-label com o nome completo do país. A maioria das bibliotecas não faz isso automaticamente. Um ícone de bandeira sozinho não transmite informação suficiente para leitores de tela. Adicione também um título ou um texto alternativo que inclua o nome do país em português, já que o público-alvo pode ser lusófono.
Há ainda a questão do cache. Se você decide hospedar os SVGs no próprio servidor, configure expires headers para pelo menos uma semana. As bandeiras não mudam com frequência. Cada pedido desnecessário sobrecarrega o CDN e aumenta o tempo de carregamento em redes móveis. Eu configurei um cache de 30 dias e adicionei versionamento nos nomes dos arquivos quando fiz uma atualização de paleta de cores. Se você está começando do zero e quer algo rápido, a abordagem mais direta é:
- Instalar a flag-icon-css via npm
- Configurar o bundler para tree-shake os ícones
- Sobrescrever manualmente as bandeiras críticas com SVGs oficiais
- Adicionar aria-label em cada ocorrência
Isso costuma levar entre 20 e 40 minutos para um projeto médio, dependendo da complexidade do seletor e do número de países envolvidos. Para projetos maiores, com mais de 50 países, o tempo dobra porque a validação dos SVGs e o mapeamento de códigos ocupam boa parte da atividade. Uma alternativa que merece consideração é usar a API do REST Countries combinada com uma biblioteca de ícones via CDN. Ela entrega dados atualizados e bandeiras em SVG sem necessidade de manutenção interna. A desvantagem é a dependência de um serviço externo. Se o domínio cair, todas as bandeiras do seu site somem. Para aplicações críticas, como e-commerce, manter os ativos internamente é mais seguro.
O custo de manter os SVGs atualizados é baixo. Uma verificação trimestral, usando um script que compara o hash dos arquivos locais com as versões oficiais dos sites governamentais, leva cerca de quinze minutos e evita surpresas como bandeiras desatualizadas em lançamentos recentes. Para download direto, o repositório da flag-icon-css no GitHub oferece pacotes completos. A flagcdn disponibiliza URLs diretas por código de país, como flagcdn.com/br.svg para o Brasil. Ambas são opções válidas. A escolha depende do nível de controle que o projeto exige.
