Propriedade CSS @charset

A at-rule @charset declara a codificação de caracteres usada em uma folha de estilos externa. A codificação de caracteres mapeia os bytes brutos de um arquivo para caracteres legíveis, portanto o navegador precisa saber qual codificação uma folha de estilos usa antes de interpretar corretamente textos não-ASCII — letras acentuadas, símbolos monetários, emoji ou conteúdo dentro de declarações content: "…".

Esta página aborda quando @charset realmente se aplica, as regras de sintaxe rígidas que tornam fácil errar, como o navegador decide qual codificação prevalece e as armadilhas comuns a evitar.

Quando @charset se aplica?

@charset destina-se estritamente a folhas de estilos externas (um arquivo .css separado, vinculado com <link> ou importado com @import). Ele é ignorado quando:

• Aparece dentro de um bloco HTML <style>.
• Aparece dentro de um atributo style inline.
• Não é a primeira coisa no arquivo.

Em um documento HTML, você define a codificação com a tag <meta charset>, não com @charset.

Na prática, raramente você precisa de @charset: se você salvar sua folha de estilos como UTF-8 (o padrão para quase todos os editores e a codificação recomendada para a web), o navegador geralmente a detecta corretamente. @charset é mais relevante para folhas de estilos legadas armazenadas em codificações não-UTF-8, ou como uma salvaguarda explícita.

Sintaxe

@charset "encoding";

A regra aceita uma única string com o nome de uma codificação do registro IANA, como "UTF-8" ou "iso-8859-15".

A sintaxe é incomumente rígida — @charset não é uma at-rule normal e não respeita a flexibilidade habitual do CSS em relação a espaços em branco e comentários:

• Deve ser o primeiro byte da folha de estilos. Nenhum caractere, comentário ou espaço em branco pode preceder.
• A codificação deve estar entre aspas duplas.
• Deve haver exatamente um espaço entre @charset e a aspa de abertura.
• A linha deve terminar com ponto e vírgula.

@charset "UTF-8"; /* Set the stylesheet encoding to Unicode UTF-8 */

Uso válido vs. inválido

Por causa das regras rígidas acima, pequenas diferenças de formatação tornam a regra válida ou ignorada:

@charset "UTF-8";        /* Valid: standard form */
@charset "ISO-8859-15";  /* Valid: any registered encoding name */
 @charset "UTF-8";       /* Invalid: a space precedes the at-rule */
@charset 'UTF-8';        /* Invalid: single quotes are not allowed */
@charset  "UTF-8";       /* Invalid: more than one space after @charset */
@charset "UTF-8"         /* Invalid: missing the closing semicolon */
@charset UTF-8;          /* Invalid: the value must be quoted */

Quando @charset é inválido ou ignorado, o navegador não gera um erro — ele simplesmente recorre à próxima fonte de codificação que encontrar.

Como o navegador escolhe uma codificação

@charset é apenas um dos vários sinais, e possui uma prioridade fixa. O navegador usa a primeira fonte que encontra, nesta ordem:

1. Uma marca de ordem de byte (BOM) no início do arquivo.
2. O parâmetro charset do cabeçalho de resposta HTTP Content-Type (ex.: text/css; charset=utf-8).
3. A at-rule @charset.
4. O atributo charset no elemento <link> que carregou a folha de estilos (obsoleto).
5. A codificação do documento de referência.
6. UTF-8 como alternativa.

Como um cabeçalho Content-Type enviado pelo servidor tem prioridade sobre @charset, um servidor mal configurado pode substituir a codificação declarada. Esse é um motivo pelo qual definir a codificação no nível HTTP (ou simplesmente usar UTF-8 em todo lugar) é a abordagem mais confiável.

Valores

@charset aceita uma única string entre aspas com o nome da codificação de caracteres, por exemplo "UTF-8" ou "iso-8859-1". Ele não aceita as palavras-chave initial ou inherit — essas se aplicam a propriedades CSS, e @charset é uma at-rule, não uma propriedade.

At-rules relacionadas

• @import — importa uma folha de estilos em outra. Se usada, as regras @import devem vir logo após qualquer @charset.
• @media — aplica estilos condicionalmente com base em recursos de mídia.
• @font-face — carrega e nomeia fontes web personalizadas.

Prática