Máscaras SVG em CSS: mantenha a silhueta e defina a cor

Uma máscara SVG em CSS controla quais partes de um elemento permanecem visíveis. Para um ícone de uma só cor, use a silhueta do SVG como máscara e pinte o elemento com background-color: currentColor. O ícone então recebe sua cor visível do CSS, em vez de exibir a paleta original do SVG.

Comece pela transparência da imagem original. Um retângulo opaco atrás da arte pode transformar o ícone pretendido em um bloco sólido. Uma abertura transparente precisa continuar transparente se você quer que a página abaixo apareça através dela.

A referência de mask-image da MDN descreve como a imagem de origem e o modo de máscara determinam a visibilidade. A tarefa prática é preparar uma silhueta útil, escolher sua interpretação e inspecioná-la no tamanho usado pela interface.

Use uma máscara quando o objetivo for uma silhueta pintada

Considere um ícone de marcador de página com uma abertura em losango e uma pequena faixa coral. Como imagem SVG comum, ele tem duas cores. Como máscara alfa sobre um elemento azul, a arte opaca revela azul; a faixa coral deixa de aparecer como uma cor separada.

Isso é útil para um ícone de interface que acompanha o tema. Seria uma escolha ruim de entrega para uma ilustração cujas diferenças de cor carregam significado.

Se você precisa editar preenchimentos e contornos SVG individuais, use o guia de edição de cores SVG. A máscara é útil quando a própria silhueta é a parte reutilizável. Para um limite geométrico definido, ajuste um recorte SVG personalizado ao alvo e escolha entre esticar a silhueta e preservar suas proporções.

Prepare uma imagem original pequena com uma abertura real

Salve este exemplo original como bookmark.svg:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
  <path fill="#087f8c" fill-rule="evenodd"
    d="M5 3H19V21L12 17L5 21Z M12 6L15 9L12 12L9 9Z"/>
  <rect x="9" y="13" width="6" height="2" fill="#e76f51"/>
</svg>

O primeiro traçado contém o marcador externo e sua abertura em losango. Não há retângulo de fundo que cubra toda a área. O pequeno segundo retângulo é a faixa coral.

Abra o SVG sobre um fundo contrastante antes de usá-lo como máscara. Confira se você consegue ver através do losango e ao redor do limite externo. Um losango branco pintado sobre um marcador sólido pareceria semelhante em uma página branca, mas ainda seria opaco em uma máscara alfa.

Para um recurso existente, inspecione qualquer forma de fundo além do motivo visível. O guia de fundo transparente SVG aborda a diferença entre espaço vazio e um retângulo branco.

Pinte o elemento do ícone com CSS

Coloque icon.css ao lado do SVG e use estas regras:

.bookmark-icon {
  display: inline-block;
  width: 1.5rem;
  height: 1.5rem;
  background-color: currentColor;
  mask-image: url("./bookmark.svg");
  mask-mode: alpha;
  mask-repeat: no-repeat;
  mask-position: center;
  mask-size: contain;
}
.save-button {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
  color: #175cd3;
}

Use um rótulo visível no botão:

<button class="save-button" type="button">
  <span class="bookmark-icon" aria-hidden="true"></span>
  Save article
</button>

Aqui, o ícone acompanha “Save article”, então é escondido da árvore de acessibilidade, em vez de repetir esse rótulo. O exemplo mostra apenas a apresentação; conecte separadamente o botão à ação de salvar do aplicativo.

O elemento precisa de uma caixa para pintar, por isso o CSS define sua largura, altura e display. currentColor usa sua cor de texto. Alterar o color do botão muda a pintura do ícone sem reescrever bookmark.svg.

A referência de mask-size define contain como ajustar a imagem inteira da máscara preservando suas proporções. Com centralização e sem repetição, isso faz a imagem original ocupar uma caixa de ícone previsível. O guia de máscaras do web.dev aborda esses controles de tamanho e repetição.

Sirva o exemplo por HTTP, inclusive ao testar localmente. A descrição de mask-image da MDN alerta que arquivos de imagem locais file:// não são aceitas nesse uso. Uma imagem de máscara ausente ou que falha ao carregar pode deixar invisível o elemento mascarado.

Diferencie uma imagem SVG de um elemento de máscara SVG

Um arquivo SVG usado como imagem e uma referência a um elemento SVG <mask> são entradas diferentes. Não escolha o modo apenas porque o nome do arquivo termina em .svg.

A referência de mask-mode especifica esse padrão dependente da entrada. Na interpretação alfa, preto opaco e branco opaco revelam o elemento. Na interpretação de luminância, branco opaco revela e preto esconde; valores intermediários podem produzir visibilidade parcial.

mask-type se aplica a um elemento SVG <mask> e usa luminância por padrão, conforme a referência de mask-type. Adicioná-lo ao span comum do ícone não muda a interpretação de uma máscara de imagem. Use mask-mode no elemento mascarado quando precisar especificar esse comportamento.

O exemplo do marcador usa uma imagem SVG externa comum e escolhe alfa explicitamente. Teste as propriedades usadas nos navegadores compatíveis; o suporte ao recurso mais amplo de máscaras não comprova suporte a todas as combinações de modo e entrada.

Diagnostique um quadrado, um ícone ausente ou uma abertura preenchida

Um teste negativo útil é colocar um retângulo branco opaco que cubra toda a área atrás de uma cópia de bookmark.svg. Com interpretação alfa, essa cópia revela toda a área da máscara. Alterar o retângulo de branco para preto não restaura a silhueta porque as duas cores continuam opacas.

Remova o fundo indesejado da imagem original, em vez de ajustar a cor do elemento. Mantenha o arquivo original para comparar a cópia corrigida.

Mantenha esses testes separados. Uma requisição de imagem bem-sucedida não comprova que a imagem original tem a transparência correta, e transparência correta não dá a um elemento largura ou altura ausentes.

Avalie o resultado no tamanho do componente

Amplie o marcador para inspecionar seus contornos e volte ao tamanho real da interface. Confira a abertura em losango, o entalhe inferior e o espaço entre o ícone e seu rótulo. A versão ampliada ajuda a encontrar defeitos; a versão pequena informa se o desenho é útil.

Experimente dois fundos contrastantes de página e duas cores de ícone. A abertura deve mostrar a cor da página em cada caso. Se ela continua branca, volte à estrutura da imagem original.

Para uma família de ícones, compare símbolos vizinhos no mesmo tamanho CSS. Seus viewBoxes podem conter quantidades diferentes de espaço vazio, fazendo caixas iguais parecerem desiguais. O guia de preparação de ícones para kits de interface aborda esse trabalho de consistência.

Recupere uma silhueta raster apenas quando a imagem original precisar

Um PNG transparente já pode ser uma máscara CSS; a conversão SVG não é um requisito para máscaras. Mantenha um arquivo vetorial original limpo existente quando você a tiver.

Se um ícone útil existe apenas como uma imagem raster irregular, o fluxo de PNG para SVG do PerfectVector pode ajudar a preparar uma versão candidata editável. Recorte até o motivo, inspecione a prévia vetorial em busca de regiões de fundo e aberturas perdidas e baixe o SVG. Use esse arquivo na máscara e repita as verificações no tamanho do componente.

Para o marcador, avalie o entalhe externo e a abertura em losango antes de se preocupar com a faixa coral original. A pintura uniforme da máscara absorverá a cor dessa faixa de qualquer maneira. Uma ilustração multicolorida complicada pode precisar de outro tratamento; escolha a silhueta deliberadamente, em vez de vetorizar cada detalhe.

A visão geral de vetorização de imagens explica a recuperação da imagem original de maneira mais ampla. Um arquivo vetorial ainda precisa de uma forma útil e de transparência adequada para esse fluxo CSS.

Perguntas frequentes

Uma máscara SVG mantém as cores originais? Uma máscara controla a visibilidade. No exemplo de fundo uniforme, o elemento fornece uma cor, então as cores separadas da imagem original não são mantidas.

Por que meu ícone se torna um quadrado sólido? Confira se há um fundo opaco que cobre toda a imagem original da máscara. Na interpretação alfa, branco e preto opacos revelam o elemento.

Máscaras SVG são sempre máscaras de luminância? Não. Uma imagem SVG comum normalmente usa alfa com match-source. Um elemento mask SVG usa luminância por padrão, a menos que sua interpretação seja alterada.

Preciso converter um PNG transparente para SVG? Não. PNG pode fornecer uma imagem de máscara. A vetorização é opcional quando você precisa recuperar ou editar uma silhueta adequada de uma imagem raster original.

Fontes

1. MDN — mask-image — Entradas de imagem, falhas de carregamento, requisitos de servidor local e visibilidade.
2. MDN — mask-mode — Alfa, luminância e padrões dependentes da entrada.
3. MDN — mask-type — Interpretação de um elemento de máscara SVG.
4. MDN — mask-size — Dimensionamento contain e proporções de imagem.
5. web.dev — aplicar efeitos a imagens com CSS mask-image — Máscaras de imagem, dimensionamento e repetição.

Comece com um ícone e confira sua silhueta, abertura e tamanho final de interface. Se uma imagem raster original precisa de recuperação, prepare uma versão candidata em SVG, inspecione sua transparência e teste-a com a pintura CSS que a interface usará.