Editorial review: Document the path-length CSS property

[chrisdavidmills]

Description

Chrome 150 adds support for the SVG path-length CSS property: see https://chromestatus.com/feature/4861677550043136.

This PR documents the new property.

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs (4 pages)

• /en-US/docs/Web/CSS/Reference/Properties/path-length
• /en-US/docs/Web/CSS/Reference/Properties
• /en-US/docs/Web/SVG/Reference/Attribute/pathLength
• /en-US/docs/Web/SVG/Reference/Attribute

Flaws (10)

Note! 3 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/SVG/Reference/Attribute
Title: SVG Attribute reference
Flaw count: 10

• macros:
  • Macro svgattr produces link /en-US/docs/Web/SVG/Reference/Attribute/hreflang which doesn't resolve
  • Macro svgattr produces link /en-US/docs/Web/SVG/Reference/Attribute/offset which doesn't resolve
  • Macro svgattr produces link /en-US/docs/Web/SVG/Reference/Attribute/ping which doesn't resolve
  • Macro svgattr produces link /en-US/docs/Web/SVG/Reference/Attribute/referrerPolicy which doesn't resolve
  • Macro svgattr produces link /en-US/docs/Web/SVG/Reference/Attribute/rel which doesn't resolve
  • and 5 more flaws omitted

(comment last updated: 2026-07-22 07:45:49)

[hamishwillee]

Note, not planning on looking at this until pinged/it says editorial review.

[chrisdavidmills]

Note, not planning on looking at this until pinged/it says editorial review.

@hamishwillee I've updated the PR title. I think you can look at this when you find the time. The tech review contact has been unresponsive, but it's not particularly complex.

[hamishwillee]

@chrisdavidmills My queue is a bit hammered - as you will see by delays on some of your other reviews. I am doing these in "things I think I can close fastest order". Upshot, I will do it, but don't expect all that much from me this week.

[chrisdavidmills]

@chrisdavidmills My queue is a bit hammered - as you will see by delays on some of your other reviews. I am doing these in "things I think I can close fastest order". Upshot, I will do it, but don't expect all that much from me this week.

Understood, and no worries 👍

[hamishwillee]

What's a user unit? Without a knowledge of user units this is quite abstract. It is hard to understand what is going on and more important, why this matters in any way, shape or form. Why would I use this? What does this scaling do for me that not having it would prevent?

MDN does not help - I think https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Positions#what_are_pixels is probably just wrong in some respects. It is certainly inconsistent in its terminology and doesn't help with this case.

Anyway, I think the point is that some properties, such as stroke-dasharray, are specified in user units - in this case "units per dash". So the svg path length had some original calculated user units that results in some calculation of how many dashes there would normally be shown. Now we're saying you can use this property to specify what the length of the path should be, and that will be used to scale the calculations, and in this case change the number and length of dashes.

I'm really not sure what can be done here, or even if this is where things can/should be updated. But I am still confused :-( Consider this a "fat nit" - it would be nice if you can help people like me understand this here, but perhaps it is out of scope.

[chrisdavidmills]

I just assumed that a user unit was well-known to SVG folks.

Ye gods, that page you linked to is confusingly written. That definitely needs some sorting out at some point, but this PR is not the place to do it.

For now, I've added a short definition of what a user unit is to the path-length page itself. I'm not sure this is ideal, but it helps this particular case for now.

[hamishwillee]

I've added a note that the added sentence is wrong and needs looking at.

But yes, I accept that it's too big a job to scope in this PR - though I would dearly like you to, because I suspect that SVG folks might not get this either - at least not from MDN. I'm not even sure "calibrate the browsers ..." is correct - certainly it isn't the point of this property - the "reason we need it".

At high level the concept is pretty clear - the SVG is defined in some arbitrary user units and then rendered in a viewport - which provides the scaling to real units. The path-length allows you to scale the effective length of a path element, which then forces other elements that are defined in terms of the user units to also scale. But how you work out what those units are, and why/when this is useful is not clear at all.

[hamishwillee]

The other problem is that without this it isn't possible to know what "calibrate the browsers ..." means. I.e. back to "practically, what is this for".

[chrisdavidmills]

I've trimmed this text down to:

The path-length CSS property specifies a total path length, in user units. All path computations are then scaled using the ratio path-length / (computed value of path length) — this includes text paths, animation paths, and various stroke operations.

This seems to make a bit more sense, but it still relies on understanding what a user unit is.

[hamishwillee]

"which is typically equivalent to one pixel on the output device."

I don't think this is true. I think the SVG image in user units has no default mapping to pixels until you define the viewport. Then if you specify that the length/width were 200 say and the box definiing the user units was to be a box from 0,0 to 100,100 you would be stating that each user unit was scaled to 2 pixels square.

[hamishwillee]

PS Issue added : #44858

[chrisdavidmills]

OK, fine, I've removed it again. ;-)

I honestly don't know anything about this, and this is what sites I found appeared to be saying it was.

Anyway, this is not the right place to be defining user units.

Luckily, someone has done some work to fix your issue, which I've reviewed. Looks like it needs some more work, but the additions so far seem to make sense.

[hamishwillee]

The last round of updates fixed the wrong bits. I suspect that with the example this is enough to give users a flavour for what it is about. Thanks very much @chrisdavidmills