SVG dashed and dotted lines: stroke-dasharray

A dashed line in SVG is an ordinary stroked line with one more attribute: stroke-dasharray. Its value is a list of lengths, read as dash, gap, dash, gap, and repeated along the whole line. stroke-dasharray="12 6" gives dashes 12 units long with gaps of 6. For a dotted line, use a dash of zero length with round ends: stroke-dasharray="0 10" stroke-linecap="round". The attribute works on every stroked shape, not only on <line>.

A dashed line

A complete file:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 40">
  <line x1="10" y1="20" x2="190" y2="20" stroke="black" stroke-width="2"
        stroke-dasharray="12 6"/>
</svg>

The line is 180 units long and each dash with its gap takes 18, so it shows ten dashes. The pattern starts with a dash at the line’s first point, here the left end.

A dotted line

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 40">
  <line x1="10" y1="20" x2="190" y2="20" stroke="black" stroke-width="4"
        stroke-linecap="round" stroke-dasharray="0 10"/>
</svg>

Also a complete file. Each dash has no length, but stroke-linecap="round" puts a rounded end on both sides of it, and two half circles on nothing make a full circle. The result is a row of round dots, as wide as the stroke (4 units), with their centres 10 units apart. Change stroke-width to change the size of the dots and the second number to change their spacing.

With stroke-linecap="square" the same code gives square dots.

The syntax

Value	Result
`12 6`	Dash 12, gap 6
`6`	Dash 6, gap 6. One number is used for both
`12 4 2 4`	Long dash, gap, short dash, gap: a dash-dot line
`0 10` with round caps	Round dots, 10 apart
`12 4 2`	An odd count is repeated to make it even: dash 12, gap 4, dash 2, gap 12, dash 4, gap 2
`none`	A solid line. The default

The numbers can be separated by spaces or commas.
Lengths are in the drawing’s own units, the same as stroke-width, so the dashes scale with the SVG.
Negative numbers are not allowed. If every number is zero, the line is drawn solid.
There must be a stroke to see: set stroke to a colour. On open shapes, add fill="none" so the shape is not filled in as well.

stroke-dasharray is also a CSS property, so it can be set in a style sheet or a style attribute, as in style="stroke-dasharray: 12 6", on any SVG shape that CSS can reach.

Line ends change the dashes

stroke-linecap applies to every dash, not just to the two ends of the line. round and square both add half the stroke width to each end of each dash. The dashes get longer and the gaps get shorter by one stroke width.

`stroke-dasharray="8 4"`, `stroke-width="4"`	What is seen
`stroke-linecap="butt"` (the default)	Dashes of 8, gaps of 4
`stroke-linecap="round"`	Dashes of 12 with rounded ends that just touch: a chain of beads, with no clear gap

So with round or square caps, make the gap larger than the stroke width, by the size of gap wanted.

Where the pattern starts: stroke-dashoffset

The pattern begins at the first point of the shape and runs in the direction the shape is drawn.

Shape	Starts at	Runs
`<line>`	`x1`, `y1`	To `x2`, `y2`
`<rect>`	The top left corner, after any rounding	Clockwise
`<circle>`, `<ellipse>`	The rightmost point, at 3 o’clock	Clockwise
`<path>`, `<polyline>`, `<polygon>`	The first point	In the order written

stroke-dashoffset slides the pattern along. A positive value starts the line part way into the pattern: with stroke-dasharray="12 6", an offset of 6 makes the first dash 6 long, because the first 6 units of it have slid off the start. A negative value pushes the pattern the other way. Animating this property is how a line is made to draw itself, which SVG animation with CSS explains.

Even dashes around a circle or a rectangle

On a closed shape the pattern rarely fits a whole number of times, and the last dash is cut short where it meets the first. The pathLength attribute fixes this without arithmetic. It tells the browser to treat the outline as if it were a given length, and dashes are then measured on that scale. A complete file:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <circle cx="50" cy="50" r="40" fill="none" stroke="black" stroke-width="3"
          pathLength="24" stroke-dasharray="1 1"/>
</svg>

The circle’s outline is declared to be 24 units long, so dashes of 1 with gaps of 1 fit exactly twelve times: twelve equal dashes and twelve equal gaps, with no odd one where the ends meet. For twenty dashes, write pathLength="40".

Only the dash lengths are rescaled. stroke-width is still in the drawing’s ordinary units. Current browsers accept pathLength on all the basic shapes. Other software may honour it only on <path>, or not at all, so check the result wherever the file will be used.

Without pathLength, the sum is: circumference divided by the number of dashes gives the length of one dash and gap together. A circle of radius 40 is about 251.3 units round, so twelve dashes need stroke-dasharray="10.47 10.47".

Dashed outlines on other shapes

The same attributes work on <rect>, <circle>, <path>, <polygon> and even <text>. A dashed box for a coupon, pasted into an HTML page:

<svg viewBox="0 0 200 100" width="300" height="150">
  <rect x="5" y="5" width="190" height="90" rx="8" fill="none"
        stroke="black" stroke-width="2" stroke-dasharray="8 6"/>
</svg>

On a rectangle the corners fall wherever the pattern happens to be, so one corner may get a dash and another a gap. Rounded corners hide this well. SVG shapes covers the shapes and SVG fill and stroke the other stroke attributes.

Dashed lines and cutting machines

A dash pattern is a way of painting a line. The path underneath is still one unbroken line. Cutting, laser and plotter software follows paths, and most of it takes no notice of how they are painted, so a dashed line in an SVG is usually cut or drawn as a solid one.

What to do depends on the aim:

A tear-off or fold line on a Cricut. Leave the line solid in the file and change its Operation in Design Space. Cricut’s help pages list Perforate, for machines that take the Perforation Blade, and Score among the operations.
Dashes that must be cut or engraved as drawn. Turn the pattern into real shapes in a vector editor. In Inkscape, Path, Stroke to Path replaces the painted line with an outline around each dash. That suits engraving and cutting slots. It does not give single cut lines.
A dotted line as decoration for printing or for the web. Nothing needs to change: browsers and print software draw the pattern as written.

Common problems

What you see	Cause	Fix
The line is solid	The dashes are tiny against the scale of the drawing, or round caps have closed the gaps	Use larger numbers, or a gap wider than the stroke
Nothing is drawn	No `stroke` colour	Add `stroke="black"` or another colour
The shape is filled in black	Shapes are filled by default	Add `fill="none"`
Dots come out as short dashes	The dash is not zero, or the caps are not round	`stroke-dasharray="0 10"` with `stroke-linecap="round"`
One short dash where a circle closes	The pattern does not divide the outline evenly	Use `pathLength`
The dashes change size when the SVG is resized	Dash lengths are in the drawing’s units	That is expected. Choose values to suit the final size
A cutter cuts a solid line	Cutting software ignores the paint	Use Perforate or Score, or convert the dashes to shapes
The dashes start in the wrong place	The pattern starts at the shape’s first point	Shift it with `stroke-dashoffset`

Questions

Is there a dotted or dashed keyword, as in CSS borders? No. SVG has only the list of lengths, which is more work and gives exact control.

Can dashes have different colours? Not on one line. Draw two copies of the line on top of each other, each with its own colour and an offset.

Can the pattern be checked quickly? Paste any example from this page into the SVG viewer, change the numbers in the code box, and the picture redraws as you type.