How to Make Any SVG Path a CSS Clip Path

The clip-path property is a relatively new and not fully supported (or old and fully supported, depending when you’re reading this) CSS property.^[2] It allows using a shape to specify a clipping region for the given HTML element: a region outside of which the element is not drawn. In other words, the clipping region is like a mask^[3] that only lets through portions of the background within the region’s interior (or equivalently, that blocks the portions of the background outside of the region). For instance, here is a 200×200 image, followed by the same image with a circled-star icon as its clipping path.

Note how the clipping region is centered over the image and fills the entire space; we’ll come back to this later. For now, let’s just confirm this fact by overlaying the clipped image on a dimmed copy of the original.

From now on, we’ll always show our clipped images overlaid on a dimmed copy of the full image.

Valid clip-paths are in approximately one-to-one correspondence with shapes in SVG: you can clip with circles, polygons, paths, and more:

Thankfully, unlike their SVG counterparts, these clip-path shapes understand dimensions written in CSS units and even some special keywords. So it’s easy to write, say, “clip this element with an ellipse that extends precisely to its horizontal and vertical edges”: it’s just clip-path: ellipse(50% 50% at center). Couldn’t be easier.

That is, unless you’re using clip-path: path(…​), which takes a good old-fashioned SVG path string, which does not support these fancy CSS units. Not only do SVG paths use a somewhat arcane syntax, but they also must be written in terms of unit-less numbers, which specify the location of their path’s elements, such as a line, an arc, or a Bezier curve, in absolute units on the Cartesian plane. This is counter to other numbers in CSS, which almost universally require units — 1px, 2em, 3rem, 4vw, etc.^[4]

Therefore, if you want to use a path to clip an element, you must know the dimensions of the element. For instance, to draw a path that references the center of the element, you would need to know the width and height of the element and then divide them by 2 yourself. 50% just isn’t available in path(…​).

There is one other way to specify a shape to use as clip-path: the clip-path: url(#clippath-id) syntax. This looks up the <clipPath> element with the given ID — which must live in some SVG on the page — and uses the union of the regions clipped by its shapes^[5] to construct the clipping region. The <clipPath> itself is not drawn in the SVG; it is merely referenced by other shapes or HTML elements, who use it as their clip-path.

But <clipPath>s are still SVG elements, so they are drawn in absolute coordinates. Here is the source code of the circled-star <clipPath> we’ve been using.

As we can tell from the viewBox (but more on that later), the dimensions of this icon are 100×100. So, if we tried to tried to naively convert it to a <clipPath>, as shown below…​

…​and we use it as the clip-path of our image, which has dimensions 200×200, using the following CSS…​

then we end up with this:

This time, the clipping region does not take up the entire image; it exists entirely within the 100×100 region in the upper left because the width and height of the <clipPath>’s <path> were both 100.^[7] So, how can we fix this to achieve what we saw above? How can we get the clipping region to span the entire 200×200 image?

Very helpfully, <clipPath> has an attribute, clipPathUnits, that lets us specify exactly what the units of the <clipPath> represent. The default value, userSpaceOnUse, leads to the behavior we just saw: it assumes the <clipPath> and the HTML element it is clipping use the same coordinate system. So, our <clipPath>, which only existed in the square from (0, 0) to (100, 100), created a clipping region that only exposed the part of the image in that same upper-left square.

The other choice for clipPathUnits is objectBoundingBox, which assumes that the <clipPath> occupies a merely 1×1 square, which is then stretched or compressed in both dimensions so that it has the same dimensions as the element it is clipping.

Let’s add clipPathUnits="objectBoundingBox" to our <clipPath> above and use it to clip our image again.

But that’s just the background. Where’d our clipped image go?

As mentioned, objectBoundingBox assumes that the <clipPath> occupies a merely 1×1 square. But our <clipPath> actually still occupies a 100×100 square, and it was stretched so that the top-left unit square fills the 200×200 image — a factor of 200. This means the entire <clipPath> was blown up to 20,000×20,000! It completely missed the image; the region it would expose is way, way down to the bottom right. We have to figure out how to get our <clipPath>’s <path> down into a 1×1 square.

The hard way to do this would be to simply edit our <path>: take all the numbers and divide them by 100 (except for the boolean flags!). But this would be tedious and would make it hard to just use any old SVG icon as a <clipPath>. Thankfully, there is a very easy way to transform SVG elements, which is…​ the transform attribute. transform applies a linear transformation to an element, and scaling by a factor of 1/100 is a linear transformation, so we’re good. All we have to do is add transform: scale(.01) to the <path> (not to the <clipPath>!), and we get a lovely 1×1 <clipPath> which clips as we expect. This is precisely how the original clipped image in this article was created.

For completeness, here is the final SVG. (In case you’re copy-pasting this somewhere, note that we’ve changed the id of the <clipPath>.)

For images that aren’t square, the <clipPath> scales separately in each dimension. Here’s just the left half of our image, and next to it is what happens when we use the circled star to clip just that half (which is now twice as tall as it is wide).

But what happens when it’s the <clipPath> that isn’t square?

So far we’ve been taking advantage of a very nice property of our <clipPath>: its width and height are the same, so we could scale them down by the same amount. This meant that if the original path was centered in its 100×100 bounding box, then the clipping region would also be centered in the element it was clipping.

But what if it weren’t square? Here is an up-arrow icon that which is taller (16) than it is wide (10):

Now is a good time to talk about the SVG’s viewBox attribute. If you imagine the SVG’s contents lying in the infinite Cartesian plane, the viewBox tells us what rectangle in the plane to restrict our attention to; nothing outside this rectangle is drawn. (In a sense, the viewBox is like a rectangular clip-path of the whole SVG, which would otherwise be infinitely large and almost entirely empty.) viewBoxes take the form of "x y w h", where x is the x-position of the rectangle’s upper left corner, y is that corner’s y-position, and w and h are the rectangle’s width and height, respectively. The up-arrow SVG has its origin at (x, y) = (0, 0) and has a width of 10 and a height of 16.

Anyway, here’s that up-arrow icon. (The border is just a guide; it’s not actually part of the icon.)

How do we use this as a clip-path? What we’d like to achieve is an arrow-shaped clipping region the same size as, and centered on the image, as shown below.

So, how do we make this happen?

Let’s try our transform trick from above; maybe it’ll still work here.

This is close, but not quite right — it isn’t centered. Eyeballing, it looks like it only covers the left five-eighths of the image. Hmm.

Why isn’t it centered? Well, the original icon had a width of 10 and a height of 16. When we scaled it by 1/16 = 0.0625, we made sure the new height went from 0 to 1. But the new width also got divided by 16, which means that it only goes from 0 to 10/16 = 5/8 = 0.625, which indeed is not all the way over to 1. That’s why the arrow above only seems to cover the left five-eighths of the image — its maximum x-coordinate is only 5/8.

So what can we do about this? A bad solution would be to scale the width and height separately. While this would get the <clipPath>’s <path> to have dimensions 1×1, it would not preserve the original aspect ratio, and so we’d be using a fundamentally different shape. Here’s what that would look like, with transform: scale(0.1 0.625).

Yech.

What we need to do is translate our correctly-scaled-down <path> so that it’s centered in the 1×1 box. But how much do we need to translate it by? After scaling it down, its left edge was at 0 and its right edge was at 5/8, so we need to shift it to the right by (1 - 5/8)/2, or 3/16 = 0.1875. If an arbitrary shape’s upper left corner is at (x, y) = (0, 0) and the shape has width w and height h, then its center is at (w/2, h/2). Assuming without loss of generality that w < h, after scaling it down by 1/h the center would end up at (w/(2*h), 1/2). The translation that moves this point to (0.5, 0.5) would be (0.5-w/(2*h), 0), or ((1-w/h)/2, 0), which is indeed what we found above. So the correct transformation to apply to the <path> would be transform: translate(0.1875 0) scale(0.0625) — that’s “scale by 1/16, then translate x and y by 3/16 and 0, respectively”.^[8] If our <clipPath> was wider than it was tall, say, 200×100, then we’d scale it by 1/200 = .005 and translate it downward by (1 - 100/200)/2 = 0.25.

We’ve solved the problem for SVGs whose viewBox's origin is at (x, y) = (0, 0). What about for SVGs whose origin is elsewhere?^[9] If the viewBox is "x y w h", then the center of the shape would be at (x+w/2, y+h/2). Again assuming that w < h, we’d scale by 1/h to get it to fit in a a 1×1 square, which would move the center to ((x+w/2)/h, (y+h/2)/h). Then, to get the center to be located at (0.5, 0.5), we’d translate it by (0.5-(x+w/2)/h, 0.5-(y+h/2)/h). The resulting transformation would be

At this point we’ve technically solved the problem. But the solution is pretty ugly; it requires an annoying amount of busywork with a calculator and there is no way to see where the decimals in the transform came from at a glance. There is also a strong implicit dependence on w being smaller than h. We can do better!

What we would really like to do, if it were possible, is center the <path> first, and then scale it down. However, the scale(…​) transform always scales relative to the origin: the result of scaling a point (x, y) by s will always be (s*x, s*y). You don’t get to specify your own “scale origin”, so translating and then scaling won’t work.^[10]

If what we’re looking for is a simpler way to translate our post-scale <path> — something simpler than translate(0.5-(x+w/2)/h, 0.5-(y+h/2)/h) — maybe we should perform the scaling on the shape when it’s centered at the origin. Then translating it to the correct final position would simply be translate(.5 .5) — that’s the center of a 1×1 square, after all. But how can we get the shape to be centered at the origin?

Easy: we simply apply translate(-(x+w/2) -(y+h/2)) first! This moves the shape’s center to the origin of the coordinate system, which means the “scale origin”, which is always the actual origin, now corresponds to the object’s center, which is exactly the point about which we would like to scale. So, to scale our <path> correctly, we simply need the following:

To make the translations really explicit, we can even split them up:

In English (remember, the functions are applied right to left):

Why is this better? To start, we’ve got only one calculation we might need a calculator for, and that’s 1/max(w, h); w/h is just gone altogether. In addition, if, say, w changes, it’s trivial to update translate(-w/2 -h/2) with the new value of w/2, and if w < h remains the same then that’s the only change you have to make at all. Finally, this transform is self-documenting in two ways. First, you have the original viewBox of the <path> written out in translate(-w/2 -h/2) translate(-x -y). And second, while the decimal number in the scale(…​) is inscrutable except in the simplest cases, when you write the transform this way, you know it’s just the reciprocal of twice the larger of the two numbers in translate(-w/2 -h/2).

Putting it all together, then:

Which, as expected, leads to this:

Success!

If we only ever wanted to place a <clipPath> in the center of our element and have it cover the whole element, we know everything we need to know. But we can use this same technique to apply more exotic transformations to <clipPath> elements as well.

A simple next step would be to have our <clipPath> remain centered, but be smaller than its full size. This is easy to do: we just change the scale from 1/h to something smaller. If we want our arrow to be half-size, we’ll scale it by half of 1/16, or 1/32 = 0.03125.

This gets us

To go even further, suppose we wanted a <clipPath> consisting of four copies of the arrow, each of which clips one of the corners of the original image and is rotated 90° from the previous one. Rather than scale the <path>s down to 1×1, we’ll scale them down to 0.5×0.5. And instead of translating them to (0.5, 0.5), we’ll translate them to (0.5±0.25, 0.5±0.25). Since, like scaling transformations, rotations are always applied about the origin, we apply the rotation before the final translation so that the shapes are rotated about their center.

We now know how to take just about any SVG shape at all, such as <path>, <ellipse>, and <polygon>, and turn it into a <clipPath>. But what about collections of shapes? If an SVG contains several shapes, what’s the right way to form a <clipPath> out of them? We’ll need a way to transform them all in lock step.

It’s simple to adapt the above technique to this more complex problem.

So, suppose we had the following SVG, which contains four circles equally spaced around its center.

Again, I’ll draw a border around the SVG.

To turn these four circles into a <clipPath>, we’ll just follow the instructions above. The viewBox is "-25 -100 50 100", so the initial translation is translate(-25 -50) translate(25 100), or translate(0 50). The largest dimension is the height, 100. So, the transformation we need is (in CSS syntax, since that’s how it happens to actually be applied on this page):

And the SVG we need is

This results in

It works!