Exploring the CSS Paint API: Image Fragmentation Effect
Tags: css, webdev, tutorial, codepen
Published: 2021-08-26 14:15:03

In [my previous article](https://dev.to/afif/css-only-fragmentation-effect-using-one-element-18kg), I created a fragmentation effect using CSS mask and custom properties. It was a neat effect but it has one drawback: it uses a lot of CSS code (generated using Sass). This time I am going to redo the same effect but rely on the new Paint API. This drastically reduces the amount of CSS and completely removes the need for Sass.

Here is what we are making. Like in the previous article, only Chrome and Edge support this for now.

{% codepen https://codepen.io/t_afif/pen/GRWeqmZ %}

See that? No more than five CSS declarations and yet we get a pretty cool hover animation.

---

## What is the Paint API?

The [Paint API](https://developer.mozilla.org/en-US/docs/Web/API/CSS_Painting_API) is part of the Houdini project. Yes, "Houdini" the strange term that everyone is talking about. A lot of articles already cover the theoretical aspect of it, so I won't bother you with more. If I have to sum it up in a few words, I would simply say : **it's the future of CSS**. The Paint API (and the other APIs that fall under the Houdini umbrella) allow us to extend CSS with our own functionalities. We no longer need to wait for the release of new features because we can do it ourselves!

From [the specification](https://www.w3.org/TR/css-paint-api-1/):

>An API for allowing web developers to define a custom CSS `<image>` with javascript [sic], which will respond to style and size changes.

And from [the explainer](https://github.com/w3c/css-houdini-drafts/blob/main/css-paint-api/EXPLAINER.md):

>The CSS Paint API is being developed to improve the extensibility of CSS. Specifically this allows developers to write a paint function which allows us to draw directly into an elements [sic] background, border, or content.

I think the idea is pretty clear. We can draw what we want. Let’s start with a very basic demo of background coloration:

{% codepen https://codepen.io/t_afif/pen/qBmdbbR %}


1. We add the paint worklet using `CSS.paintWorklet.addModule('your_js_file')`.
2. We register a new paint method called draw.
3. Inside that, we create a `paint()` function where we do all the work. And guess what? Everything is like working with `<canvas>`. That `ctx` is the 2D context, and I simply used some well-known functions to draw a red rectangle covering the whole area.

This may look unintuitive at first glance, but notice that the main structure is always the same: the three steps above are the "copy/paste" part that you repeat for each project. The real work is the code we write inside the `paint()` function.

Let's add a variable:

{% codepen https://codepen.io/t_afif/pen/ExmjPwZ %}

As you can see, the logic is pretty simple. We define the getter `inputProperties` with our variables as an array. We add properties as a third parameter to `paint()` and later we get our variable using `properties.get()`.

That's it! Now we have everything we need to build our complex fragmentation effect.

---

## Building the mask

You may wonder why the paint API to create a fragmentation effect. We said it’s a tool to draw images so how it will allow us to fragment an image?

In the previous article, I did the effect using different mask layer where each one is a square defined with a gradient (remember that a gradient is an image) so we got a kind of matrix and the trick was to adjust the alpha channel of each one individually.

This time, instead of using many gradients we will define only one custom image for our mask and that custom image will be handled by our paint API.

An example please!

{% codepen https://codepen.io/t_afif/pen/NWjGbLN %}

In the above, I have created an image having an opaque color covering the left part and a semi-transparent one covering the right part. Applying this image as a mask gives us the logical result of a half-transparent image.

Now all we need to do is to split our image to more parts. Let's define two variables and update our code:

{% codepen https://codepen.io/t_afif/pen/PomPbrP %}

The relevant part of the code is the following:

```javascript
const n = properties.get('--f-n');
const m = properties.get('--f-m');

const w = size.width/n;
const h = size.height/m;

for(var i=0;i<n;i++) {
  for(var j=0;j<m;j++) {
    ctx.fillStyle = 'rgba(0,0,0,'+(Math.random())+')';    
    ctx.fillRect(i*w, j*h, w, h);
  }
}
```

`N` and `M` define the dimension of our matrix of rectangles. `W` and `H` are the size of each rectangle. Then we have a basic FOR loop to fill each rectangle with a random transparent color.

With a little JavaScript, we get a custom mask that we can easily control by adjusting the CSS variables:

{% codepen https://codepen.io/t_afif/pen/ExmVZbM %}

Now, we need to control the alpha channel in order to create the fading effect of each rectangle and build the fragmentation effect.

Let's introduce a third variable that we use for the alpha channel that we also change on hover.

{% codepen https://codepen.io/t_afif/pen/NWjGdMw %}

We defined a CSS custom property as a `<number>` that we transition from 1 to 0, and that same property is used to define the alpha channel of our rectangles. Nothing fancy will happen on hover because all the rectangles will fade the same way.

We need a trick to prevent fading of all the rectangles at the same time, instead creating a delay between them. Here is an illustration to explain the idea I am going to use:

![delay fading](https://i1.wp.com/css-tricks.com/wp-content/uploads/2021/07/s_E6C4D332440E78DDA3A024FDD6B5D40ED567175E7EC6A5C5A5899C409624BA2D_1625697558693_Screenshotfrom2021-07-0800-39-00.png?w=471&ssl=1)

The above is showing the alpha animation for two rectangles. First we define a variable `L` that should be bigger or equal to 1 then for each rectangle of our matrix (i.e. for each alpha channel) we perform a transition between X and Y where `X - Y = L` so we have the same overall duration for all the alpha channel. `X` should be bigger or equal to 1 and `Y` smaller or equal to 0.

Wait, the alpha value shouldn’t be in the range `[1 0]`, right ?

Yes, it should! And all the tricks that we’re working on rely on that. Above, the alpha is animating from 8 to -2, meaning we have an opaque color in the `[8 1]` range, a transparent one in the `[0 -2]` range and an animation within `[1 0]`. In other words, any value bigger than 1 will have the same effect as 1, and any value smaller than 0 will have the same effect as 0.

Animation within `[1 0]` will not happen at the same time for both our rectangles. Rectangle 2 will reach `[1 0]` before Rectangle 1 will. We apply this to all the alpha channels to get our delayed animations.

In our code we will update this:

```
rgba(0,0,0,'+(o)+')
```

…to this:

```
rgba(0,0,0,'+((Math.random()*(l-1) + 1) - (1-o)*l)+')
```

`L` is the variable illustrated previously, and `O` is the value of our CSS variable that transitions from 1 to 0

When `O=1`, we have `Math.random()*(l-1) + 1`. Considering the fact that the `random()` function gives us a value within the `[0 1]` range, the final value will be in the `[L 1]` range.

When `O=0`, we have `Math.random()*(l-1) + 1 - l` and a value with the `[0 1-L]` range.

`L` is our variable to control the delay.

Let's see this in action:

{% codepen https://codepen.io/t_afif/pen/xxdVBaa %}

We are getting closer. We have a cool fragmentation effect but not the one we saw in the beginning of the article. This one isn’t as smooth.

The issue is related the `random()` function. We said that each alpha channel need to animate between `X` and `Y`, so logically those value need to remain the same. But the `paint()` function is called a bunch during the transition, so each time, the `random()` function give us different `X` and `Y` values for each alpha channel; hence the "random" effect we are getting.

To fix this we need to find a way to store the generated value so they are always the same for each call of the `paint()` function. Let's consider a pseudo-random function, a function that always generates the same sequence of values. In other words, we want to [control the seed](https://en.wikipedia.org/wiki/Random_seed).

Unfortunately, we cannot do this with the JavaScript's built-in `random()` function, so like any good developer, let’s pick one up from [Stack Overflow](https://stackoverflow.com/a/19301306/8620333):

```javascript
const mask = 0xffffffff;
const seed = 30; /* update this to change the generated sequence */
let m_w  = (123456789 + seed) & mask;
let m_z  = (987654321 - seed) & mask;

let random =  function() {
  m_z = (36969 * (m_z & 65535) + (m_z >>> 16)) & mask;
  m_w = (18000 * (m_w & 65535) + (m_w >>> 16)) & mask;
  var result = ((m_z << 16) + (m_w & 65535)) >>> 0;
  result /= 4294967296;
  return result;
}
```

And the result becomes:

{% codepen https://codepen.io/t_afif/pen/yLbOwwz %}

We have our fragmentation effect without complex code:

* a basic nested loop to create `NxM` rectangles
* a clever formula for the channel alpha to create the transition delay
* a ready `random()` function taken from the Net

That’s it! All you have to do is to apply the mask property to any element and adjust the CSS variables.

--
## Fighting the gaps!

If you play with the above demos you will notice, in some particular case, strange gaps between the rectangles

![CSS fragmentation gap](https://i0.wp.com/css-tricks.com/wp-content/uploads/2021/07/s_E6C4D332440E78DDA3A024FDD6B5D40ED567175E7EC6A5C5A5899C409624BA2D_1626444259040_image.png?w=306&ssl=1)

To avoid this, we can extend the area of each rectangle with a small offset.

We update this:

```
ctx.fillRect(i*w, j*h, w, h);
```

…with this:

```
ctx.fillRect(i*w-.5, j*h-.5, w+.5, h+.5);
```

It creates a small overlap between the rectangles that compensates for the gaps between them. There is no particular logic with the value 0.5 I used. You can go bigger or smaller based on your use case.

{% codepen https://codepen.io/t_afif/pen/oNWWxmr %}

---

## Want more shapes?

Can the above be extended to consider more than rectangular shape? Sure it can! Let's not forget that we can use Canvas to draw any kind of shape — unlike pure CSS shapes where we sometimes need some hacky code. Let's try to build that triangular fragmentation effect.

After searching the web, I found something called [Delaunay triangulation](https://en.wikipedia.org/wiki/Delaunay_triangulation). I won't go into the deep theory behind it, but it's an algorithm for a set of points to draw connected triangles with specific properties. There are lots of ready-to-use implementations of it, but we’ll go with [Delaunator](https://github.com/mapbox/delaunator) because it's supposed to be the fastest of the bunch.

We first define a set of points (we will use `random()` here) then run Delauntor to generate the triangles for us. In this case, we only need one variable that defines the number of points.

```javascript
const n = properties.get('--f-n');
const o = properties.get('--f-o');
const w = size.width;
const h = size.height;
const l = 7; 

var dots = [[0,0],[0,w],[h,0],[w,h]]; /* we always include the corners */
/* we generate N random points within the area of the element */
for (var i = 0; i < n; i++) {
  dots.push([random() * w, random() * h]);
}
/**/
/* We call Delaunator to generate the triangles*/
var delaunay = Delaunator.from(dots);
var triangles = delaunay.triangles;
/**/
for (var i = 0; i < triangles.length; i += 3) { /* we loop the triangles points */
  /* we draw the path of the triangles */
  ctx.beginPath();
  ctx.moveTo(dots[triangles[i]][0]    , dots[triangles[i]][1]);
  ctx.lineTo(dots[triangles[i + 1]][0], dots[triangles[i + 1]][1]);
  ctx.lineTo(dots[triangles[i + 2]][0], dots[triangles[i + 2]][1]);  
  ctx.closePath();
  /**/
  var alpha = (random()*(l-1) + 1) - (1-o)*l; /* the alpha value */
  /* we fill the area of triangle with the semi-transparent color */
  ctx.fillStyle = 'rgba(0,0,0,'+alpha+')';
  /* we consider stroke to fight the gaps */
  ctx.strokeStyle = 'rgba(0,0,0,'+alpha+')';
  ctx.stroke();
  ctx.fill();
} 
```

I have nothing more to add to the comments in the above code. I simply used some basic JavaScript and Canvas stuff and yet we have a pretty cool effect.

{% codepen https://codepen.io/t_afif/pen/jOBRMNx %}

We can make even more shapes! All we have to do is to find an algorithm for it.

I cannot move on without doing the hexagon one!

{% codepen https://codepen.io/t_afif/pen/jOmxEYW %}

I took the code from [this article](https://eperezcosano.github.io/hex-grid/) written by Izan Pérez Cosano. Our variable is now R that will define the dimension of one hexagon.

---

## What’s next?

Now that we have built our fragmentation effect, let's focus on the CSS. Notice that the effect is as simple as changing the opacity value (or the value of whichever property you are working with) of an element on it hover state.

**Opacity animation**

```css
img {
  opacity:1;
  transition:opacity 1s;
}

img:hover {
  opacity:0;
}
```

**Fragmentation effect**
```css
img {
  -webkit-mask: paint(fragmentation);
  --f-o:1;
  transition:--f-o 1s;
}

img:hover {
  --f-o:0;
}
```

This means we can easily integrate this kind of effect to create more complex animations. Here are a bunch of ideas!

### Responsive image slider

{% codepen https://codepen.io/t_afif/pen/vYmxQBL %}

Another version of the same slider:

{% codepen https://codepen.io/t_afif/pen/oNWZQex %}


### Noise effect

{% codepen https://codepen.io/t_afif/pen/XWRMyQb %}


### Loading screen

{% codepen https://codepen.io/t_afif/pen/MWmmejq %}

### Card hover effect

{% codepen https://codepen.io/t_afif/pen/MWmoJGq %}

---

## That's a wrap

And all of this is just the tip of the iceberg of what can be achieved using the Paint API. I’ll end with two important points:

* The Paint API is 90% `<canvas>`, so the more you know about `<canvas>`, the more fancy things you can do. Canvas is widely used, which means there's a bunch of documentation and writing about it to get you up to speed.
* The Paint API removes all the complexity from the CSS side of things. There's no dealing with complex and hacky code to draw cool stuff. This makes CSS code so much easier to maintain, not to mention less prone to error.

----

### <center>You want to support me?</center>

[![buy me a coffee](https://cdn.buymeacoffee.com/buttons/default-orange.png)](https://www.buymeacoffee.com/afif)

<center>**OR**</center>

[![Become a patron](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/db3jtgy2i5l4w8slkps5.png)](https://www.patreon.com/temani)