stroke-dasharray

Avatar of Geoff Graham
Geoff Graham on (Updated on )

The stroke-dasharray property in CSS sets the length of dashes in the stroke of SVG shapes. More specifically, it sets the length of a pattern of alternating dashes and the gaps between them.

path {
  stroke-dasharray: 5; /* dashes and gaps are both 5 units long */
}

It’s a ll a little confusing because stroke-dasharray is a SVG presentational attribute (e.g. <path stroke-dasharray="5" ... />) that can also be used as a CSS property in your stylesheet, like this:

As such, you’ll want to remember:

  • This will override the SVG presentation attribute, e.g. <path stroke-dasharray="5" ... />
  • This will not override an inline style, e.g. <path style="stroke-dasharray: 5;" ... />

Where to use it

First off, this property is specifically designed to work with SVG elements. Which ones? Basically any SVG shape or text element:

  • <altGlyph>
  • <circle>
  • <ellipse>
  • <path>
  • <line>
  • <polygon>
  • <polyline>
  • <rect>
  • <text>
  • <textPath>
  • <tref>
  • <tspan>

Syntax

stroke-dasharray: none | <dasharray> | inherit;
  • Initial value: none
  • Applies to: SVG shapes and text content elements
  • Inherited: yes
  • Animatable: yes (non-additive)

Values

/* Keyword values */
stroke-dasharray: none;
stroke-dasharray: inherit;

/* Length values */
stroke-dasharray: 2
stroke-dasharray: 2.5
stroke-dasharray: 2em
stroke-dasharray: 15%

/* Two-value syntax */
stroke-dasharray: 2 4
stroke-dasharray: 2 4% 5 4%
stroke-dasharray: 2em 4 6 8

Values can be separated either by spaces or commas — your choice!

Unitless values are likely the most common choice, as it is generally with SVG values. They become length units that are relative to the coordinate system set up by the viewBox.

Pattern behavior

The mind-bending thing about stroke-dasharray is that it’s merely a set of length values, but its setting both the length of the dashes and gaps between them.

If we set one value, both the dash length and gap length take that value and repeat the pattern.

But if we set two values, the first sets the dash and the second sets the gap.

If we set three values:

  • The first value sets the first dash
  • The second value sets the first gap
  • The third sets the second dash

Notice something funny there? You might think the pattern simply repeats. What actually happens is the pattern keeps cycling through those values irregardless of whether they’re applied to dashes or gaps. So what we see in that last example there is:

  • Dash: 5
  • Gap: 10
  • Dash: 15
  • Gap: 5
  • Dash: 10
  • Gap: 15
  • …and so on.

In other words:

stroke-dasharray: 5 10 15

/* is equivalent to this */
stroke-dasharray: 5 10 15 5 10 15

That way, we get a nice even pattern even though we provide an odd number of values.

stroke-dasharray: 5;             /* 5 5 */
stroke-dasharray: 5 10 15;       /* 5 10 15 5 10 15 */
stroke-dasharray: 5 10 15 20 25; /* 5 10 15 20 25 5 10 5 20 25 */

Getting tricky with stroke-dasharray

Have you ever seen those cool demos where an SVG shape appears to draw itself? That’s a trick that takes the stroke-dasharray of an element and animates it in conjunction with the stroke-dashoffset property.

.path {
  stroke-dasharray: 1000;
  stroke-dashoffset: 1000;
  animation: dash 5s linear forwards;
}

@keyframes dash {
  to {
    stroke-dashoffset: 0;
  }
}

We cover this technique in much more detail in this post. It looks like IE 11 and down doesn’t like animating the stroke properties with @keyframes, so be careful there.

Browser support

More information