Canvas setLineDash() Method

The Canvas setLineDash() method sets the dash pattern used when a path is stroked. Pass an array of numbers that alternates between drawn lengths and gaps.

The basic syntax is:

ctx.setLineDash([8, 4]);

This creates a repeating pattern of 8 canvas units of line followed by a 4-unit gap. To return to a solid stroke, use an empty array:

ctx.setLineDash([]);

Working example Top ↑

This example draws one dashed line and one solid line so you can see the effect immediately.

const canvas = document.getElementById('basicDashCanvas');
const ctx = canvas.getContext('2d');

// Dashed line
ctx.beginPath();
ctx.setLineDash([12, 6]);
ctx.moveTo(20, 40);
ctx.lineTo(470, 40);
ctx.stroke();

// Solid line
ctx.beginPath();
ctx.setLineDash([]);
ctx.moveTo(20, 90);
ctx.lineTo(470, 90);
ctx.stroke();

setLineDash() syntax and pattern rules Top ↑

setLineDash() is a method, so it must be called with parentheses. The argument is an array containing non-negative, finite numbers.

ctx.setLineDash(segments);

• [8, 4] means draw 8 units, leave a 4-unit gap, then repeat.
• [2, 3] produces a short dash/dot-like pattern.
• [] clears the dash pattern and restores a solid stroke.
• If the array contains an odd number of values, the browser duplicates the array before using it.

For example, this:

ctx.setLineDash([5, 15, 25]);

is treated as the even-length pattern:

[5, 15, 25, 5, 15, 25]

The resulting sequence then repeats along the stroked path.

Interactive dash pattern demo Top ↑

Use the controls below to change the dash length, gap, and lineDashOffset. The first canvas shows a line and the second shows a rectangle using the same dash settings.

const pattern = [dashLength, dashGap];
ctx.setLineDash(pattern);
ctx.lineDashOffset = dashOffset;
ctx.stroke();

Using lineDashOffset Top ↑

setLineDash() controls the pattern itself. The lineDashOffset property shifts that pattern forward or backward along the path. See the dedicated Canvas lineDashOffset tutorial for more examples.

ctx.setLineDash([5, 5]);
ctx.lineDashOffset = 5;
ctx.beginPath();
ctx.moveTo(20, 50);
ctx.lineTo(380, 50);
ctx.stroke();

Reading the current dash pattern Top ↑

Use getLineDash() when your script needs to inspect the current dash pattern. It returns an even-length array. If you originally supplied an odd number of values, the returned array contains the duplicated pattern.

ctx.setLineDash([4, 8]);
const currentPattern = ctx.getLineDash();
console.log(currentPattern); // [4, 8]

Marching ants effect Top ↑

A “marching ants” selection border can be created by combining a dashed stroke with an animated lineDashOffset. Instead of changing the dash lengths every frame, keep the pattern fixed and update the offset.

View the marching ants Canvas demo.

Common setLineDash() mistakes Top ↑

• Assigning instead of calling: use ctx.setLineDash([5, 5]), not ctx.setLineDash = ....
• Forgetting to stroke the path: the dash pattern affects stroked paths, so call stroke() or a stroke method such as strokeRect().
• Expecting an empty array to hide the line: [] means a solid stroke, not “no stroke.”
• Using negative or non-finite values: keep dash segment values finite and non-negative.
• Forgetting state changes: the dash pattern remains part of the current drawing state until it is changed, restored with restore(), or reset with [].
• Using Canvas for information with no alternative: important text or data drawn only into a canvas bitmap may not be available to every user. Provide an accessible alternative when the graphic communicates essential information.

Related Canvas tutorials Top ↑

Continue with HTML Canvas basics, lineDashOffset, lineWidth, lineCap, lineJoin, or strokeStyle.

Frequently asked questions Top ↑

How do I change a dashed Canvas line back to solid? Top ↑

Call ctx.setLineDash([]). An empty array clears the current dash list and restores solid strokes.

What happens if setLineDash() receives an odd-length array? Top ↑

The browser duplicates the array to make an even-length pattern. For example, [5, 10, 15] is treated as [5, 10, 15, 5, 10, 15].

What is the difference between setLineDash() and lineDashOffset? Top ↑

setLineDash() defines the lengths of dashes and gaps. lineDashOffset shifts where that repeating pattern starts along the path.

Can setLineDash() create dotted lines? Top ↑

Yes. Short dash values combined with an appropriate gap and a rounded lineCap can create a dot-like appearance. The exact visual result depends on the line width and cap style.

Does setLineDash() work with rectangles? Top ↑

Yes. Once the dash pattern is set on the 2D context, methods such as strokeRect() and stroked paths use that pattern.

Subhendu Mohapatra

Author & Instructor at plus2net

I write and maintain practical tutorials on Python, PHP, SQL, JavaScript, HTML, jQuery, and web development at plus2net. The tutorials focus on clear explanations, working examples, and code that readers can test and adapt while learning.

About the author   Watch on YouTube

Connect: