CSS Modules

Última atualização: 2026-11-03

CSS Modules CSS Modules

Os CSS Modules transformam um arquivo CSS comum em estilos com escopo local: no momento da build cada nome de classe é compilado em um identificador único no formato fileName_className_hash, então os componentes ficam naturalmente isolados e a poluição global de estilos desaparece. No React você os referencia através de um objeto styles.xxx, o que torna o isolamento de estilos uma solução de custo zero para projetos médios e grandes. Nada extra é necessário em tempo de execução.

GrupoEcossistema
TipoPadrão
DesdePadrão da comunidade — suportado nativamente por Vite / CRA / Next.js

ℹ️ Informação O editor transpila JSX para JavaScript e renderiza a UI real na sandbox; os componentes são montados automaticamente — sem render manual.

📝 Sintaxe

/* No install needed — Vite / Create React App support it out of the box */
/* Button.module.css — the file name must end with .module.css */
.title { color: #0969da; }
.active { color: #1a7f37; }

// Button.jsx — class names are referenced through the styles object
import styles from './Button.module.css'

export default function Button() {
  return <button className={styles.title}>Button</button>
}
// styles.title compiles to 'Button_title_x7s2k2', globally unique and conflict-free

Retorna:Sem valor de retorno — CSS Modules é uma solução em tempo de build; veja a sintaxe e o exemplo para aprender a usá-lo.

▶ Exemplo

O exemplo roda direto: renderiza automaticamente ao expandir e edições valem na hora.

Saída:

Simulação: a demo mostra primeiro os nomes de classe hash compilados de styles.card e styles.title, depois renderiza um card abaixo. Ao clicar no botão Activate title, o nome de classe hash active é adicionado ao título e ele fica azul. Em um projeto real, esses nomes de classe hash recebem seus estilos de um arquivo .module.css.

💡 Pontos-chave

💡 Dica O nome do arquivo deve terminar com .module.css (o mesmo vale para .module.scss e .module.less); caso contrário, a folha de estilo é tratada como global.
ℹ️ Informação Escreva os nomes de classe em camelCase no CSS (titleColor) e referencie-os como styles.titleColor, evitando a forma com colchetes styles['title-color'].
⚠️ Aviso Ao concatenar className dinamicamente, separe vários nomes de classe com um espaço — um espaço ausente faz com que ambas as classes falhem.
Mais casos em breve.

📚 Tutoriais Relacionados

❓ Perguntas Frequentes

P Qual é a diferença entre CSS Modules e CSS comum?
R Os nomes de classe do CSS comum são globais, então nomes idênticos se sobrescrevem. O CSS Modules compila os nomes de classe no momento da build em identificadores únicos no formato fileName_className_hash, então os estilos se aplicam apenas ao componente que os referencia — o isolamento vem de graça.
P Como escrevo estilos globais?
R Envolva-os em :global, por exemplo :global(.ant-btn) { … }; ou crie um arquivo CSS comum separado sem o sufixo .module e mantenha seus nomes de classe globais.
P Referenciar uma classe que não existe em styles gera um erro?
R Nenhum erro em tempo de execução: styles.xxx fica undefined e o elemento simplesmente perde a classe, o que dificulta a depuração. Projetos TypeScript podem gerar um arquivo .d.ts para que erros de digitação apareçam no momento da compilação.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%