# Borda com gradiente em CSS: quatro formas de a desenhar

[Canonical HTML page](https://gradiently.design/pt-pt/guide/css-gradient-border)

O border-color não aceita um gradiente, por isso todo o contorno com gradiente é um contorno de recurso. Eis os quatro que importam, o que cada um pode e não pode fazer e a qual recorrer.

## The short version

- O CSS não permite pôr um gradiente no border-color, por isso uma borda com gradiente em CSS desenha-se sempre com outra técnica.
- O border-image com um gradiente é o método mais curto, mas ignora o border-radius, por isso só serve para cantos retos.
- Duas camadas de fundo, uma recortada à caixa de preenchimento e outra à caixa da borda, dão uma borda com gradiente arredondada desde que o interior seja de cor lisa.
- A técnica da máscara recorta o meio de uma camada de gradiente, o que dá uma borda com gradiente arredondada com interior transparente.
- Um gradiente cónico a rodar, controlado por uma propriedade personalizada registada com @property, é a forma habitual de animar uma borda com gradiente.

Uma **borda com gradiente em CSS** é um contorno cuja cor se mistura ao longo do seu comprimento. O senão é que o `border-color` só aceita cores, não imagens, por isso não há uma propriedade única para isto. Em vez disso, desenhas o gradiente noutro lado e mostras só uma faixa fina dele. Há quatro formas fiáveis de o fazer, e a certa depende de duas perguntas: o elemento tem cantos redondos e o seu interior tem de ser transparente?

| Método | Cantos redondos | Interior transparente | Melhor para |
| --- | --- | --- | --- |
| `border-image` | Não | Sim | Cartões retos, separadores, tabelas |
| Dois fundos | Sim | Não, precisa de um preenchimento liso | A maioria dos cartões e botões |
| Máscara num pseudoelemento | Sim | Sim | Cartões sobre imagens ou gradientes |
| Pseudoelemento por trás | Sim | Não | Brilhos e anéis animados |

Escolhe pelas duas perguntas: cantos e interior.

- Violeta a ciano: `linear-gradient(135deg, #7c3aed, #22d3ee)`
- Tangerina a magenta: `linear-gradient(135deg, #f97316, #db2777)`
- Lima a verde-azulado: `linear-gradient(135deg, #a3e635, #0d9488)`
- Aresta prateada: `linear-gradient(135deg, #e5e7eb, #6b7280, #f9fafb)`

Gradientes que se leem bem como contornos finos. A saturação alta importa mais numa linha de 2px do que num fundo inteiro.

## Método 1: border-image

O `border-image` aceita qualquer imagem, incluindo um gradiente. Define uma largura e um estilo de borda, depois o gradiente e depois uma fatia de `1`, que diz ao navegador para usar a imagem toda como aresta. São duas linhas, funciona em todo o lado e deixa intacto o interior do elemento.

```css
.panel {
  border: 3px solid;
  border-image: linear-gradient(135deg, #7c3aed, #22d3ee) 1;
}
```

A borda com gradiente mais curta. O `1` é o valor da fatia; sem ele a borda só é desenhada nos cantos.

> **Sem cantos redondos** Com o `border-image`, o `border-radius` continua a recortar o fundo, mas a borda em si fica reta. Se o elemento tiver de ser arredondado, usa um dos outros métodos.

## Método 2: dois fundos com background-clip

Dá ao elemento uma borda transparente e depois empilha dois fundos. A camada de cima é o preenchimento interior, recortada à `padding-box`, por isso pára na aresta interior da borda. A camada de baixo é o gradiente, recortado à `border-box`, por isso estende-se por baixo da borda. Onde o preenchimento pára, o gradiente aparece, e segue perfeitamente o `border-radius`.

```css
.card {
  border: 2px solid transparent;
  border-radius: 16px;
  background:
    linear-gradient(#0f172a, #0f172a) padding-box,
    linear-gradient(135deg, #7c3aed, #22d3ee) border-box;
}
```

O preenchimento escreve-se como um gradiente de uma só cor porque só as imagens se podem sobrepor assim.

Este é o método a que recorrer por predefinição. O seu único limite é que o interior tem de ser opaco, porque um preenchimento transparente revelaria o gradiente por todo o cartão. Para cartões sobre uma cor de página lisa, isso não é limite nenhum: usa a cor da página como preenchimento.

> **Porque importa a forma abreviada** Escrever `border-box` uma vez na abreviatura `background` define tanto o `background-origin` como o `background-clip`, por isso o gradiente é dimensionado até à aresta exterior. Se definires só `background-clip: border-box` por extenso, o gradiente é dimensionado pela caixa de preenchimento e repete-se por baixo da borda, deixando fatias finas da cor errada ao longo das arestas.

## Método 3: a técnica da máscara para interiores transparentes

Quando o cartão está sobre uma fotografia ou outro gradiente, o meio tem de ser transparente. Põe o gradiente num pseudoelemento que cubra o cartão, dá-lhe um preenchimento igual à largura da borda e depois mascara-o com duas camadas: uma que cobre só a caixa de conteúdo e outra que cobre tudo. Excluir uma da outra deixa visível só o anel de preenchimento.

```css
.glass-card {
  position: relative;
  border-radius: 16px;
}

.glass-card::before {
  content: "";
  position: absolute;
  inset: 0;
  padding: 2px; /* border width */
  border-radius: inherit;
  background: linear-gradient(135deg, #7c3aed, #22d3ee);
  -webkit-mask:
    linear-gradient(#000 0 0) content-box,
    linear-gradient(#000 0 0);
  -webkit-mask-composite: xor;
  mask:
    linear-gradient(#000 0 0) content-box exclude,
    linear-gradient(#000 0 0);
  pointer-events: none;
}
```

Um anel com gradiente e centro transparente. O par com prefixo cobre o WebKit mais antigo; a linha `mask` padrão cobre tudo o que é atual.

O `pointer-events: none` impede que o pseudoelemento engula os cliques destinados ao conteúdo do cartão. A [referência do mask-composite da MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-composite) explica as palavras-chave de composição. Este é o método por trás da maioria dos cartões de [glassmorphism](https://gradiently.design/pt-pt/guide/glassmorphism) com arestas luminosas.

## Método 4: um pseudoelemento por trás, para brilhos e animação

Coloca um pseudoelemento de gradiente ligeiramente maior do que o cartão, por trás do seu conteúdo, e cobre o meio com um segundo pseudoelemento que leve o preenchimento liso do cartão. A aresta visível é o gradiente. Como o gradiente vive na sua própria camada, podes desfocar uma cópia dele para um brilho, ou rodá-lo.

```css
@property --angle {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

.ring {
  position: relative;
  isolation: isolate;
  border-radius: 16px;
}

.ring::before {
  content: "";
  position: absolute;
  inset: -2px;
  z-index: -1;
  border-radius: 18px;
  background: conic-gradient(from var(--angle), #7c3aed, #22d3ee, #f472b6, #7c3aed);
  animation: spin 6s linear infinite;
}

/* the card's fill, painted over the middle of the ring */
.ring::after {
  content: "";
  position: absolute;
  inset: 0;
  z-index: -1;
  border-radius: inherit;
  background: #0f172a;
}

@keyframes spin {
  to { --angle: 360deg; }
}

@media (prefers-reduced-motion: reduce) {
  .ring::before { animation: none; }
}
```

Uma borda com gradiente animada. O `--angle` registado deixa o navegador interpolar com suavidade o ângulo inicial do cónico, e o `::after` pinta o preenchimento sobre o meio.

O gradiente do anel a rodar: `conic-gradient(from 0deg, #7c3aed, #22d3ee, #f472b6, #7c3aed)`

Repetir a primeira cor no fim esconde a junção enquanto roda. Os [gradientes cónicos em CSS](https://gradiently.design/pt-pt/guide/css-conic-gradient) tratam da função em profundidade.

O raio exterior deve ser igual ao raio interior mais a largura da borda, e é por isso que o pseudoelemento usa 18px à volta de um cartão de 16px. Para mais formas de pôr movimento nos gradientes, vê os [gradientes animados em CSS](https://gradiently.design/pt-pt/guide/css-animated-gradient).

## Dicas de design para bordas com gradiente

### Evita

- Bordas com gradiente em todos os cartões de uma grelha
- Gradientes de baixa saturação numa linha de 1px, que parecem cinzentos
- Uma borda com gradiente e um preenchimento com gradiente no mesmo elemento
- Anéis a rodar depressa em conteúdo que as pessoas precisam de ler

### Faz

- Reserva a aresta com gradiente para um item em destaque, como um plano recomendado
- Usa 2px ou mais e paragens saturadas
- Um preenchimento calmo com uma aresta viva, ou o inverso
- Rotação lenta, em pausa para movimento reduzido

As bordas com gradiente funcionam melhor como ênfase. A mesma lógica aplica-se aos botões, tratados em [botões com gradiente em CSS](https://gradiently.design/pt-pt/guide/css-gradient-button).

## FAQ

### Como faço uma borda com gradiente em CSS?

A forma mais rápida é `border: 3px solid; border-image: linear-gradient(135deg, #7c3aed, #22d3ee) 1;`. Para cantos redondos, usa dois fundos recortados à `padding-box` e à `border-box`.

### Porque é que o border-radius não funciona com o border-image?

Pela especificação, uma borda desenhada com `border-image` não é arredondada pelo `border-radius`. Usa o método do background-clip ou da máscara para bordas com gradiente arredondadas.

### Como faço uma borda com gradiente com fundo transparente?

Usa a técnica da máscara: um pseudoelemento com o gradiente, preenchimento igual à largura da borda e uma máscara que exclui a sua caixa de conteúdo.

### Como animo uma borda com gradiente?

Regista um ângulo com `@property`, usa-o como ângulo `from` de um gradiente cónico num pseudoelemento e anima essa propriedade de 0deg a 360deg.

### Que método de borda com gradiente devo usar?

Usa dois fundos para a maioria dos cartões e botões arredondados, `border-image` para arestas retas e a técnica da máscara só quando o interior tem de ficar transparente.