Propriété CSS stroke-dasharray

La propriété stroke-dasharray contrôle le motif de tirets et d'espaces utilisé pour peindre le contour (stroke) d'une forme SVG. Au lieu d'un trait continu, le contour est fragmenté en une alternance de tirets et d'espaces, ce qui permet de dessiner des bordures en pointillés, des séparateurs et les traits utilisés dans les animations de dessin progressif.

Cette page explique comment la liste de valeurs est interprétée, la règle de duplication pour un nombre impair de valeurs qui déroute la plupart des développeurs, les cas d'usage courants, et comment stroke-dasharray interagit avec les propriétés associées.

Fonctionnement de la liste de valeurs

stroke-dasharray accepte soit none, soit un <dasharray> — une liste de longueurs ou de pourcentages séparés par des virgules et/ou des espaces. Les nombres sont lus dans l'ordre comme tiret, espace, tiret, espace…, et toute la liste se répète le long du tracé :

Une seule valeur — 4 dessine un tiret de 4, puis un espace de 4, en répétant. Tirets et espaces sont égaux.
Deux valeurs — 8 2 dessine un tiret de 8 unités, un espace de 2 unités, puis recommence. C'est la forme la plus courante.
Plusieurs valeurs — 4 1 2 1 alterne tiret 4, espace 1, tiret 2, espace 1, puis recommence depuis le début.

Le piège principal : si vous fournissez un nombre impair de valeurs, la liste est dupliquée pour la rendre paire. Ainsi 5 3 2 se comporte comme 5 3 2 5 3 2, soit tiret 5, espace 3, tiret 2, tiret 5, espace 3, tiret 2 — les rôles de chaque valeur s'inversent au deuxième passage. Utilisez un nombre pair de valeurs pour obtenir un motif prévisible et répétitif.

Une valeur de 0 pour un tiret produit un point lorsqu'elle est combinée avec stroke-linecap: round, ce qui permet de créer des lignes en pointillés arrondis.

Cas d'usage courants

Bordures et séparateurs en tirets ou en points sur des icônes et des illustrations, là où une border CSS ne peut pas suivre un tracé courbe ou diagonal.
Animations de dessin progressif ("self-drawing"), où stroke-dasharray est défini sur la longueur du tracé et stroke-dashoffset est animé de cette longueur jusqu'à 0, faisant apparaître le trait comme s'il se dessinait lui-même.
Anneaux de progression et indicateurs de chargement, où l'animation du tiret et de l'offset révèle un contour circulaire.

Les styles CSS en ligne remplacent les attributs de présentation SVG. Par exemple, un style en ligne stroke-dasharray: 4; prend la priorité sur l'attribut de présentation stroke-dasharray="4".

Info

La propriété stroke-dasharray peut être utilisée à la fois comme propriété CSS et comme attribut de présentation SVG. Elle peut être appliquée à n'importe quel élément, mais elle n'affecte que les éléments suivants : <altGlyph>, <circle>, <ellipse>, <path>, <line>, <polygon>, <polyline>, <rect>, <text>, <textPath>, <tref> et <tspan>.

Valeur initiale	none
S'applique à	Les formes et les éléments de contenu textuel.
Hérité	Oui.
Animable	Non.
Version	Spécification SVG 1.1
Syntaxe DOM	Object.strokeDasharray = "none";

Syntaxe

Syntaxe CSS de stroke-dasharray

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

Exemple de la propriété stroke-dasharray :

Exemple de code 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>

Essayez vous-même »

Résultat

Exemple de la propriété stroke-dasharray avec l'élément `<line>` :

Autre exemple de code 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>

Essayez vous-même »

Dans cet exemple, chaque <line> utilise un motif différent : un trait continu (sans dasharray), puis 3 (tirets et espaces égaux), 5 1 (longs tirets, petits espaces), et les motifs à valeurs impaires 4 2 2 et 4 1 3 2, qui se répètent sur deux passages comme décrit ci-dessus.

Valeurs

Valeur	Description
none	Aucun tiret n'est utilisé.
`<dasharray>`	Un motif de tirets est utilisé.
initial	Applique la valeur par défaut de la propriété.
inherit	Hérite la propriété de son élément parent.

Propriétés associées

stroke-dasharray est l'une des nombreuses propriétés qui stylisent un contour SVG. Vous l'associerez souvent à :

stroke-dashoffset — décale le point de départ du motif de tirets ; c'est la clé des animations de dessin progressif.
stroke-linecap — contrôle la forme des extrémités des tirets (butt, round, square) ; utilisez round pour transformer les tirets de longueur 0 en points.
stroke-width — définit l'épaisseur du contour.
stroke — définit la couleur du contour.
fill — définit la couleur intérieure de la forme.

Pratique

Quelle est la fonction de la propriété 'stroke-dasharray' en CSS ?

Elle définit le motif de tirets et d'espaces utilisé pour tracer les contours.Elle colore les contours tracés.Elle spécifie la largeur du contour tracé.Elle modifie le motif de tirets en répétant les valeurs.Elle crée des effets d'animation pour les contours tracés.