Circular progress bar SVG: how dasharray and dashoffset fill it

PublishedToolCSS Circular Progress Generator

Contents
  1. Why a circular progress bar looks like a donut filling up
  2. How to check it: draw it yourself by calculating the circumference
  3. Where people usually get stuck
  4. Wrapping up
  5. Under the hood: the math behind SVG and CSS
  6. Comparison of ways to build a circular UI
  7. 5 Common Mistakes When Building a Circular Progress SVG
  8. The Fail-Proof 5-Step Circular Progress Bar Workflow
  9. 7 SVG Animation Tips
  10. Decision Tree: Which Approach Fits?
  11. Terminology Cheatsheet
  12. Frequently Asked Questions

You've probably seen a circular progress bar fill up like a donut on an app's loading screen or a dashboard stat card. It isn't a pre-made image or an animated GIF. It's a single SVG circle whose border stroke is only partially drawn. Once you know how it works, you can reproduce it in code without any library.

Summary ① A circular progress bar isn't an image. It's the stroke on an SVG circle element. ② stroke-dasharray draws the line across the full circumference, and stroke-dashoffset pushes the hidden portion out of view. ③ If you know the circumference (2πr) and the progress percentage, you can calculate both values yourself.

Why a circular progress bar looks like a donut filling up

An SVG circle element has two separate parts: fill (the inside) and stroke (the border line). Make the fill transparent and paint only a thick stroke, and you get a ring shaped like a donut. Stack two of those rings, and the bottom one becomes a faint background circle while the top one shows color for just the progress amount.

The top circle shows "only as much as the progress" because of an attribute called stroke-dasharray. It's normally used to draw dotted lines, repeating a drawn segment (dash) and a gap. Set that value to exactly the full circumference, and a single dash matches one full lap of the circle, so it looks like one unbroken line.

Add stroke-dashoffset on top of that, and you can push the line's starting point along the circumference. Push the line by the offset amount and that much of it hides around the far side of the circle, so only part of it looks filled in. Rotate the circle -90 degrees with transform, and the starting point moves from 3 o'clock to 12 o'clock.

How to check it: draw it yourself by calculating the circumference

A few lines of code is all you need to do the math without a library. First, the radius (r) is the circle's diameter minus half the stroke width. The stroke is drawn along the circle's center line, so you need to leave room inward by the stroke width to keep the two circles from overlapping.

Once you have the radius, the circumference comes from the formula "2 × π × r." For example, with a diameter of 120px and a stroke width of 8px, the radius is 56px and the circumference is about 351.86px. Plug that value straight into stroke-dasharray and the whole circle draws as one solid line.

To reflect the progress, calculate stroke-dashoffset as "circumference × (1 − progress ÷ 100)." At 75% progress, that's 351.86 × 0.25, or about 87.96px as the offset. Put those two values and a -90 degree rotation on the circle tag, and your donut-shaped progress bar is done.

Check it with our tool. Every time you move the sliders for progress, thickness, and size, the circumference and offset are recalculated automatically, so you can see the result and the code right away without working out the numbers by hand.

CSS Circular Progress Generator

Free · No sign-up · Generates SVG and CSS code right in your browser

Where people usually get stuck

SymptomCause
The progress runs in the opposite directionYou flipped the sign in the stroke-dashoffset calculation, or the rotation direction is wrong.
The starting point is at the right (3 o'clock) instead of the topYou didn't set transform: rotate(-90deg) on the circle.
The background circle and progress circle don't line up at the center of the strokeYou didn't subtract half the stroke width when calculating the radius.
It snaps instead of moving when the progress changesYou didn't put a transition on stroke-dashoffset, so the value changes with no animation.

As the table shows, most of these mismatches come down to either the sign of the offset or the rotation direction. Lock in the formula and the -90 degree rotation once, and from then on you only need to change the progress number.

Wrapping up

A circular progress bar isn't an image. It's the stroke of an SVG circle drawn across the full circumference with stroke-dasharray, with stroke-dashoffset pushing the portion you want hidden out of view. With just the circumference (2πr) and the progress, you can calculate both values.

Instead of working out the radius and circumference by hand every time, move the sliders and watch how the code changes. It cuts down on mistakes.

CSS Circular Progress Generator

Free · No sign-up · Generates SVG and CSS code right in your browser


Under the hood: the math behind SVG and CSS

Behind a donut chart that looks simple, there's precise geometry and CSS physics at work.

SVG circle geometry and stroke math

  • Full SVG dimensions: W × H (for example, 120 × 120px)
  • Stroke width: S (for example, 8px)
  • Safe radius: The stroke spreads to both sides of the center line, so r = W/2 − S/2 = 60 − 4 = 56px
  • Circumference: C = 2π r ≈ 2 × 3.14159265 × 56 ≈ 351.86px

How the CSS dash properties work

  • 'stroke-dasharray: C C': Sets the length of one dash segment to the full circumference so the ring looks like a solid line.
  • 'stroke-dashoffset: C \times (1 - P / 100)': When P is the progress percentage, this pushes the start of the solid line along the circumference by that amount. The pushed-out part isn't visible, so the ring looks filled to exactly the percentage you want.

Coordinate rotation and anti-aliasing

  • By geometric convention, SVG's default 0 degree reference point is at 3 o'clock (x=r, y=0).
  • To start at 12 o'clock (the top), set 'transform: rotate(-90deg);' and the rotation origin 'transform-origin: center;' in CSS.
  • Build the smooth fill animation with 'transition: stroke-dashoffset 0.6s cubic-bezier(0.4, 0, 0.2, 1);', and round off the end of the line with 'stroke-linecap: round;'.

Comparison of ways to build a circular UI

Here's how the main techniques for building a circular progress bar compare.

CategoryPure SVG + CSS (recommended)HTML5 Canvas 'arc()'CSS 'conic-gradient' / maskAnimated GIF / Lottie
File sizeVery small (~2KB)SmallSmallLarge (tens of KB up to MB)
Vector scalabilityScales infinitely, never blursCan blur depending on resolution (DPI)Scales infinitelyGIF pixels blur / Lottie is unaffected
CPU/GPU loadVery low (easy to GPU-accelerate)CPU load from script calculationsLowHigh GPU memory use and CPU rendering load
CSS animationSmooth with 'stroke-dashoffset'Requires JS 'requestAnimationFrame'Requires '@property' (limited in older browsers)Not possible / tied to the library
Browser supportAlmost every browser, including IEAlmost every browserMostly modern browsers (partial support)IE compatible (Lottie only in modern environments)

5 Common Mistakes When Building a Circular Progress SVG

  1. Not subtracting half the stroke width from the radius: An SVG stroke extends outward in both directions from the center line of the path. Skip this step and the outer half gets pushed outside the viewBox and clipped.
  2. Leaving out transform-origin: center when rotating -90 degrees: Without a set axis of rotation, the circle pivots around the SVG's default 0,0 coordinate (top-left corner) and flies off the screen.
  3. Skipping stroke-linecap: round: The end of the progress gauge stops flat, like it was sliced with a knife, and the whole thing looks like clunky, outdated UI.
  4. Hardcoding a low-precision pi (π = 3.14): An inaccurate circumference leaves a tiny gap between the start and end points when progress hits 100%, or makes them overlap. Use Math.PI in JS.
  5. Forgetting the CSS transition: When the data changes, the gauge jumps instantly with a hard cut. Add a proper transition on the offset property so the feedback feels smooth.

The Fail-Proof 5-Step Circular Progress Bar Workflow

  1. Define the dimensions and viewBox: Pick the overall size (for example, 100x100) and set the SVG viewBox="0 0 100 100".
  2. Derive a safe radius: Choose the stroke width (for example, 10), then use the formula r = (D − stroke) / 2 to get r = 45.
  3. Calculate the circumference: Use C = 2π r to get the total length. (2 × 3.14159 × 45 = 282.74)
  4. Lay down the background track and the indicator: Stack two circles of the same size — the bottom one a light-colored track, the top one the indicator in the progress color.
  5. Apply the CSS transition and offset: Calculate stroke-dashoffset from the percentage formula, inject it as an inline style, and complete the animation with a transition.

7 SVG Animation Tips

  1. Round the ends: Make stroke-linecap: round a habit for a modern, polished UI.
  2. Fill with a gradient: Instead of a flat color, declare <defs><linearGradient> and point to it with stroke="url(#gradient)" for a richer effect.
  3. Hardware acceleration: To prevent dropped animation frames, add will-change: stroke-dashoffset to the gauge circle element.
  4. Stability at 100%: Make sure the offset lands exactly on stroke-dashoffset: 0 at 100% so even a tiny rounding error doesn't show.
  5. Tick-mark (speedometer) style: Split stroke-dasharray into a length and a gap (for example, 5 10) and you get a dashed gauge like a car dashboard instead of one solid line.
  6. Half-circle gauge: Cut the circumference in half, hide the bottom portion, then adjust the viewBox and offset formula for a half circle, and you have a speedometer-style UI.
  7. Lean on a generator: To confirm the rendering is error-free, test with real-time sliders in a web generator instead of doing the math by hand every time.

Decision Tree: Which Approach Fits?

  • Is it data visualization with lots of interaction where CSS animation is the core? ➔ The SVG stroke-dashoffset approach (recommended)
  • Do you need particle effects or pixel manipulation at more than 60 frames per second? ➔ HTML5 Canvas rendering
  • Is it a static graph where IE support doesn't matter and the code must be as short as possible? ➔ The CSS conic-gradient approach
  • Does a designer need to drop in complex motion graphics alone, without a developer? ➔ Lottie / animated GIF

Terminology Cheatsheet

  • SVG (Scalable Vector Graphics): A two-dimensional vector graphics format drawn with mathematical equations, so it never pixelates no matter how far you zoom in.
  • stroke-dasharray: A property that splits a solid line into dashed segments by setting the dash length and the gap. Here, you turn the entire circle circumference into a single dash.
  • stroke-dashoffset: An offset property that pushes the starting point of the dash pattern. Set it inversely to the progress to reveal the remaining empty section.
  • Circumference (2πr): The total length of a circle's edge. This becomes the 100% length of the progress bar.
  • viewBox: The logical coordinate system area of the SVG canvas.
  • stroke-linecap: round: An SVG property that caps both ends of a line with a rounded finish.
  • transform-origin: The central axis used as the reference point for rotation or scaling.
  • Hardware acceleration (will-change): A CSS property that hints the browser to hand an element's animation calculations to the GPU for smoother rendering.

Frequently Asked Questions

Q1. Why do I have to subtract half the stroke width from the diameter to get the radius?

A1. In SVG, a stroke grows equally on both sides of an imaginary path. If the stroke width is 10px, it grows 5px inward from the center line and 5px outward. To keep that 5px from spilling outside the canvas, you shrink the circle's own radius by 5px and tuck it inward.

Q2. Can I add a gradient that runs smoothly through multiple colors along the circular path?

A2. Yes. Use <defs> and <linearGradient> inside the SVG to set the start and end colors, then reference that gradient's id in the circle's stroke property (url(#gradient-id)). That said, a conic-gradient look where colors bend around the circle is complicated in SVG 1.1, so combining it with modern CSS functions is the better route.

Q3. How do I make the gauge drain counter-clockwise instead of filling up?

A3. To make it empty out instead of fill, flip the offset calculation formula, or rotate the circle in the opposite direction from -90 degrees while adjusting the offset direction. The simplest method is to mirror it left to right with something like transform: scaleX(-1) rotate(-90deg) to force reverse rendering.

This article was adapted from our Korean original. Read the Korean original

Related articles

  1. Why clip-path Shapes Distort: Aspect Ratio Fix ExplainedSee why clip-path stars and polygons stretch on non-square elements, how percentage coordinates are calculated, and how to check and fix the aspect ratio.
  2. Color Blindness Simulator: Why Red and Green Blur TogetherWhy red and green look alike to people with color vision deficiency, why color alone shouldn't carry meaning, and how to check your palette.
  3. WCAG Contrast Ratio 4.5:1: Where the Numbers Come FromSee how the WCAG 4.5:1 and 3:1 contrast thresholds are calculated from relative luminance, and why large text gets a lower requirement.
  4. RGB color distance formula: check your color match accuracyLearn how RGB Euclidean distance turns color differences into a 0–100 match score, then practice with a free slider game.
  5. Color Palette Generator: Why Random Colors Still HarmonizeSee how a palette generator picks 5 random colors that still harmonize, using hue angles plus fixed saturation and lightness ranges you can check by hand.
  6. What Is a Complementary Color? 180° Rule and HSL AnglesA complementary color sits exactly 180° away on the color wheel. See how analogous, triadic, and tetradic schemes split the hue circle, plus the HSL math.

Related tools