Docs executáveis de CSS: Imagem de fundo

Q: Como colocar uma imagem de fundo no CSS?

Use background-image: url("photo.jpg"); no elemento. O caminho é relativo ao arquivo CSS (ou à página, no caso de um atributo style ou de um elemento ). Dê um tamanho ao elemento, porque um fundo nunca faz um elemento vazio crescer.

Q: Como fazer a imagem de fundo cobrir o elemento inteiro?

Use background-size: cover; com background-position: center;. A imagem é redimensionada até preencher a caixa por completo, mantendo as proporções, e o que sobra é cortado.

Q: Qual a diferença entre cover e contain?

cover preenche a caixa inteira e corta o que não cabe. contain mostra a imagem inteira e deixa espaço vazio em dois lados quando as proporções são diferentes.

Q: Como impedir que a imagem de fundo se repita?

Acrescente background-repeat: no-repeat;. Por padrão, uma imagem de fundo se repete nas duas direções para preencher o elemento.

Q: Por que minha imagem de fundo não aparece?

As causas comuns são um caminho errado em url() (ele é relativo ao arquivo CSS), um elemento sem altura porque não tem conteúdo ou um shorthand background posterior que zerou a imagem.

Como colocar uma imagem de fundo

background-image pinta uma imagem atrás do conteúdo, do padding e da borda do elemento. Por padrão, ela começa no canto superior esquerdo da caixa do padding, mantém o tamanho natural e se repete para preencher a caixa:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Background image</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    .dots {
      /* a 24x24 image: one blue dot */
      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24'%3E%3Ccircle cx='12' cy='12' r='4' fill='%232563eb'/%3E%3C/svg%3E");
      height: 120px;
      padding: 16px;
      border: 2px solid #111827;
      font-weight: 600;
    }
  </style>
</head>
<body>
  <div class="dots">One 24px image, repeated to fill the box</div>
</body>
</html>

Em um projeto real, o url() aponta para um arquivo: url("images/hero.jpg"). O caminho é relativo à folha de estilo que o contém (ou à página, no caso de um elemento <style>). Os exemplos desta página usam pequenas imagens SVG escritas inline como URLs data:, para funcionarem em qualquer lugar.

Duas coisas para saber desde o começo:

Um fundo não dá tamanho a um elemento. Uma div vazia com imagem de fundo tem 0px de altura. Dê a ela conteúdo, padding, um height ou um aspect-ratio.
Uma imagem de fundo é decoração. Leitores de tela a ignoram e ela não tem texto alternativo. Uma imagem que carrega significado vai em um elemento <img>.

background-size: cover, contain e comprimentos

background-size redimensiona a imagem. As duas palavras-chave mantêm as proporções:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>cover vs contain</title>
  <style>
    body { font-family: system-ui, sans-serif; font-size: 14px; }
    .row { display: flex; gap: 12px; flex-wrap: wrap; }
    .box {
      --landscape: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='200' viewBox='0 0 400 200'%3E%3Crect width='400' height='200' fill='%23bfdbfe'/%3E%3Ccircle cx='320' cy='50' r='24' fill='%23f59e0b'/%3E%3Cpath d='M0 200L120 70L220 200Z' fill='%2316a34a'/%3E%3Cpath d='M140 200L270 90L400 200Z' fill='%2315803d'/%3E%3C/svg%3E");
      width: 160px; height: 160px;
      background: var(--landscape) center / auto no-repeat, #e5e7eb;
      border: 2px solid #111827;
    }
    .cover { background-size: cover; }
    .contain { background-size: contain; }
    .stretch { background-size: 100% 100%; }
  </style>
</head>
<body>
  <div class="row">
    <div><div class="box"></div>auto (400x200, cropped)</div>
    <div><div class="box cover"></div>cover</div>
    <div><div class="box contain"></div>contain</div>
    <div><div class="box stretch"></div>100% 100% (distorted)</div>
  </div>
</body>
</html>

A imagem tem o dobro da largura em relação à altura, e cada caixa é quadrada.

Valor	Resultado
`auto` (padrão)	O tamanho da própria imagem
`cover`	Redimensiona até a caixa ficar totalmente preenchida; o excesso é cortado
`contain`	Redimensiona até a imagem inteira caber; sobram faixas cinza em dois lados
`200px`	200px de largura, altura proporcional
`50% auto`	Metade da largura da caixa, altura proporcional
`100% 100%`	Exatamente o tamanho da caixa; distorce a imagem se as proporções forem diferentes

cover é a escolha comum para banners de destaque e cards. contain é para logos e ilustrações que nunca podem ser cortadas.

background-position e background-repeat

background-position posiciona a imagem dentro da caixa, com palavras-chave (top, center, bottom, left, right), porcentagens ou comprimentos. background-repeat controla a repetição. Teste alguns valores:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Position and repeat</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    #box {
      height: 140px; margin-top: 10px;
      border: 2px solid #111827;
      background-color: #f3f4f6;
      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24'%3E%3Ccircle cx='12' cy='12' r='4' fill='%232563eb'/%3E%3C/svg%3E");
      background-size: 48px;
    }
    label { display: block; margin-top: 6px; }
  </style>
</head>
<body>
  <label>background-position: <input id="pos" value="center" size="18"></label>
  <label>background-repeat: <input id="rep" value="no-repeat" size="18"></label>
  <div id="box"></div>
  <script>
    const box = document.getElementById('box');
    const pos = document.getElementById('pos');
    const rep = document.getElementById('rep');
    const show = () => {
      box.style.backgroundPosition = pos.value;
      box.style.backgroundRepeat = rep.value;
    };
    pos.addEventListener('input', show);
    rep.addEventListener('input', show);
    show();
  </script>
</body>
</html>

Experimente as posições top right, bottom 10px right 20px e 25% 75%, e os valores de repetição repeat-x, repeat-y, space (repete com espaços para nenhuma ser cortada) e round (redimensiona as repetições para caber um número inteiro delas).

Camadas: vários fundos e texto por cima

background-image recebe uma lista separada por vírgulas. A primeira camada é desenhada por cima. O uso comum é um degradê semitransparente sobre uma foto, para que um texto branco continue legível:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Overlay</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; }
    .hero {
      --landscape: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='200' viewBox='0 0 400 200'%3E%3Crect width='400' height='200' fill='%23bfdbfe'/%3E%3Ccircle cx='320' cy='50' r='24' fill='%23f59e0b'/%3E%3Cpath d='M0 200L120 70L220 200Z' fill='%2316a34a'/%3E%3Cpath d='M140 200L270 90L400 200Z' fill='%2315803d'/%3E%3C/svg%3E");
      background-image:
        linear-gradient(rgb(17 24 39 / 10%), rgb(17 24 39 / 75%)),
        var(--landscape);
      background-size: cover;
      background-position: center;
      aspect-ratio: 16 / 7;
      display: flex; align-items: end;
      padding: 20px; box-sizing: border-box;
      color: white;
    }
    h1 { margin: 0; font-size: 32px; }
  </style>
</head>
<body>
  <div class="hero" id="hero"><h1>Readable over an image</h1></div>
</body>
</html>

aspect-ratio dá altura à caixa vazia, e background-size: cover vale para as duas camadas. Para mais receitas de degradê, veja degradês CSS.

O shorthand background

background define todas as propriedades de fundo em uma linha. O tamanho precisa vir logo depois da posição, separado por uma barra, e a cor vai na última camada:

.hero {
  background: url("hero.jpg") center / cover no-repeat, #1f2937;
}
/* the same as */
.hero {
  background-image: url("hero.jpg");
  background-position: center;
  background-size: cover;
  background-repeat: no-repeat;
  background-color: #1f2937;
}

A cor de reserva aparece enquanto a imagem carrega, e também se ela falhar. Qualquer propriedade que você deixar de fora do shorthand volta ao padrão, então coloque o shorthand primeiro e as propriedades individuais depois.

Outras propriedades de fundo

Propriedade	O que faz
`background-attachment: fixed`	A imagem fica parada enquanto a página rola (ignorado no Safari do iOS)
`background-origin`	Se a posição começa na borda, no padding ou no conteúdo
`background-clip`	Onde o fundo é pintado, incluindo `text` para preencher as letras
`background-blend-mode`	Mistura as camadas, como `multiply`

Erros comuns

Um caminho errado. O url() em uma folha de estilo é relativo ao arquivo CSS, não à página HTML.
Um elemento vazio. Ele não tem altura, então a imagem não tem onde aparecer.
Esquecer o no-repeat com contain ou com uma imagem pequena: ela se repete.
Esticar com 100% 100% quando você queria cover.
Imagens importantes como fundo. Use <img> com texto alternativo para conteúdo; fundos são invisíveis para leitores de tela.
Faltar aspas em uma URL data: que contém espaços ou aspas. Escreva sempre url("...").

Perguntas frequentes

Como colocar uma imagem de fundo no CSS?

Use background-image: url("photo.jpg"); no elemento. O caminho é relativo ao arquivo CSS (ou à página, no caso de um atributo style ou de um elemento <style>). Dê um tamanho ao elemento, porque um fundo nunca faz um elemento vazio crescer.

Como fazer a imagem de fundo cobrir o elemento inteiro?

Use background-size: cover; com background-position: center;. A imagem é redimensionada até preencher a caixa por completo, mantendo as proporções, e o que sobra é cortado.

Qual a diferença entre cover e contain?

cover preenche a caixa inteira e corta o que não cabe. contain mostra a imagem inteira e deixa espaço vazio em dois lados quando as proporções são diferentes.

Como impedir que a imagem de fundo se repita?

Acrescente background-repeat: no-repeat;. Por padrão, uma imagem de fundo se repete nas duas direções para preencher o elemento.

Por que minha imagem de fundo não aparece?

As causas comuns são um caminho errado em url() (ele é relativo ao arquivo CSS), um elemento sem altura porque não tem conteúdo ou um shorthand background posterior que zerou a imagem.

Conceitos relacionados