Propriedade CSS stroke-dasharray

A propriedade stroke-dasharray controla o padrão de traços e espaços usados para pintar o contorno (stroke) de uma forma SVG. Em vez de uma linha sólida, o stroke é dividido em traços e espaços alternados, permitindo criar bordas tracejadas e pontilhadas, separadores e as linhas usadas em animações de desenho de traço.

Esta página explica como a lista de valores é interpretada, a regra de repetição para número ímpar de valores que costuma confundir as pessoas, os casos de uso mais comuns e como stroke-dasharray interage com propriedades relacionadas.

Como funciona a lista de valores

stroke-dasharray aceita none ou um <dasharray> — uma lista de comprimentos ou porcentagens separados por vírgulas e/ou espaços em branco. Os números são lidos em ordem como traço, espaço, traço, espaço…, e a lista inteira se repete ao longo do caminho:

Um valor — 4 desenha um traço de 4, depois um espaço de 4, e repete. Traços e espaços iguais.
Dois valores — 8 2 desenha um traço de 8 unidades, um espaço de 2 unidades, e repete. Esta é a forma mais comum.
Vários valores — 4 1 2 1 alterna entre traço 4, espaço 1, traço 2, espaço 1, e recomeça.

O ponto de atenção principal: se você fornecer um número ímpar de valores, a lista é duplicada para ficar par. Assim, 5 3 2 se comporta como 5 3 2 5 3 2, ou seja, traço 5, espaço 3, traço 2, traço 5, espaço 3, traço 2 — os papéis de cada número se invertem na segunda passagem. Use um número par sempre que quiser um padrão repetitivo e previsível.

Um valor 0 para um traço produz um ponto quando combinado com stroke-linecap: round, que é como se criam linhas pontilhadas arredondadas.

Casos de uso comuns

Bordas ou separadores tracejados e pontilhados em ícones e ilustrações, onde uma border CSS não pode seguir um caminho curvo ou diagonal.
Animações de desenho de linha ("self-drawing"), onde stroke-dasharray é definido com o comprimento do caminho e stroke-dashoffset é animado desse comprimento até 0, fazendo o traço parecer que está se desenhando.
Anéis de progresso e carregadores, onde animar o traço e o offset revela um stroke circular.

Estilos CSS inline substituem atributos de apresentação SVG. Por exemplo, um estilo inline stroke-dasharray: 4; tem precedência sobre o atributo de apresentação stroke-dasharray="4".

Informação

A propriedade stroke-dasharray pode ser usada tanto como propriedade CSS quanto como atributo de apresentação SVG. Pode ser aplicada a qualquer elemento, mas afeta apenas os seguintes elementos: <altGlyph>, <circle>, <ellipse>, <path>, <line>, <polygon>, <polyline>, <rect>, <text>, <textPath>, <tref> e <tspan>.

Valor Inicial	none
Aplica-se a	Elementos de forma e conteúdo de texto.
Herdado	Sim.
Animável	Não.
Versão	Especificação SVG 1.1
Sintaxe DOM	Object.strokeDasharray = "none";

Sintaxe

Sintaxe CSS do stroke-dasharray

stroke-dasharray: none | <dasharray> | initial | inherit;

Exemplo da propriedade stroke-dasharray:

Exemplo de código CSS stroke-dasharray

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <h2>Stroke-dasharray property example</h2>
    <svg height="80" width="300">
      <g fill="none" stroke="black" stroke-width="4">
        <path stroke-dasharray="6,6" d="M5 20 l215 0" />
        <path stroke-dasharray="8,10" d="M5 40 l215 0" />
        <path stroke-dasharray="18,10,6,7,7,10" d="M5 60 l215 0" />
      </g>
    </svg>
  </body>
</html>

Experimente Você Mesmo »

Resultado

Exemplo da propriedade stroke-dasharray com o elemento `<line>`:

Outro exemplo de código CSS stroke-dasharray

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <h2>Stroke-dasharray property example</h2>
    <svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
      <line x1="0" y1="1" x2="30" y2="1" stroke="#1c98c9" />
      <line x1="0" y1="3" x2="30" y2="3" stroke="#8ebf42"
        stroke-dasharray="3" />
      <line x1="0" y1="5" x2="30" y2="5" stroke="#000"
        stroke-dasharray="5 1" />
      <line x1="0" y1="7" x2="30" y2="7" stroke="#ccc"
        stroke-dasharray="4 2 2" />
      <line x1="0" y1="9" x2="30" y2="9" stroke="#666"
        stroke-dasharray="4 1 3 2" />
    </svg>
  </body>
</html>

Experimente Você Mesmo »

Neste exemplo, cada <line> usa um padrão diferente: uma linha sólida (sem dasharray), depois 3 (traços e espaços iguais), 5 1 (traços longos, espaços pequenos) e os padrões com número ímpar 4 2 2 e 4 1 3 2, que se repetem em duas passagens conforme descrito acima.

Valores

Valor	Descrição
none	Nenhum traço é utilizado.
`<dasharray>`	Um padrão de traços é utilizado.
initial	Faz a propriedade usar seu valor padrão.
inherit	Herda a propriedade do elemento pai.

Propriedades relacionadas

stroke-dasharray é uma das várias propriedades que estilizam o contorno de um SVG. Você frequentemente a combinará com:

stroke-dashoffset — desloca o ponto de início do padrão de traços; é a chave para as animações de desenho de linha.
stroke-linecap — controla a forma das extremidades dos traços (butt, round, square); use round para transformar traços de comprimento 0 em pontos.
stroke-width — define a espessura do stroke.
stroke — define a cor do stroke.
fill — define a cor interior da forma.

Prática

Qual é a função da propriedade 'stroke-dasharray' no CSS?

Define o padrão de traços e espaços usados para traçar caminhos.Colore os caminhos do stroke.Especifica a largura do caminho do stroke.Modifica o padrão de traços repetindo os valores.Cria efeitos de animação para caminhos de stroke.