CSS Houdini Blobs

A CSS Houdini Paint Worklet to draw blobs.

Usage

1. Getting `css-houdini-blobs`

Using a pre-built hosted version

The easiest way to get css-houdini-blobs is to use the prebuilt version through UNPKG. Just skip ahead to step 2 in that case.

Installing it Locally

You can install the css-houdini-blobs locally using NPM.

npm install @timbroddin/css-houdini-blobs

Alternatively you can clone the css-houdini-blobs repo and after manually build the project:

cd css-houdini-blobs
npm install
npm run build

You'll find the built file in the ./dist folder.

2. Loading `css-houdini-blobs`

To include it you must loads the module in the given JavaScript file and add it to the Paint Worklet.

If you want to use the UNPKG hosted version of css-houdini-blobs, use https://unpkg.com/@timbroddin/css-houdini-blobs/dist/blobs.js as the moduleURL.

if ("paintWorklet" in CSS) {
  CSS.paintWorklet.addModule(
    "https://unpkg.com/@timbroddin/css-houdini-blobs/dist/blobs.js"
  );
}

If you've installed css-houdini-blobs using NPM or have manually built it, refer to its url:

if ("paintWorklet" in CSS) {
  CSS.paintWorklet.addModule("url/to/blobs.js");
}

A note on older browsers

To add support for browsers that don't speak Houdini, you can include the css-paint-polyfill before loading the Worklet.

<script>
  (async function () {
    if (CSS["paintWorklet"] === undefined) {
      await import("https://unpkg.com/css-paint-polyfill");
    }

    CSS.paintWorklet.addModule(
      "https://unpkg.com/@timbroddin/css-houdini-blobs/dist/blobs.js"
    );
  })();
</script>

3. Applying `css-houdini-blobs`

To use Circles Paint Worklet you need to set the background-image property to paint(circles)

.element {
  background-image: paint(blobs);
}

Configuration

You can tweak the appearance of the Cicles Paint Worklet by setting some CSS Custom Properties

property	description	default value
--colors	Colors To Use, one or more hexadecimal colors comma separated	`#71a7ee, #7940c1`
--min-extra-points	Minimum extra points, the minimum amount of extra points (you get 3 points for free) for each blob	`1`
--max-extra-points	Maximum extra points, the maximum amount of extra points (you get 3 points for free) for each blob	`1`
--min-randomness	Minimum randomness, the minimum amount of randomness to add to each point	`20`
--max-randomness	Maximum randomness, the maximum amount of randomness to add to each point	`20`
--min-size	Minimum size, the minimum size of each blob	`20`
--max-size	Maximum size, the maximum size of each blob	`400`
--num-blobs	Number of blobs to draw	`5`
--offset-x	X-offset	`0`
--offset-x y	Y-offset	`0`
--min-opacity	Minimum Opacity, minimum blob opacity (as a float: 0.00 – 1.00)	`0.5`
--max-opacity	Maximum Opacity, maximum blob opacity (as a float: 0.00 – 1.00)	`1`
--seed	Seed for the "predictable random" generator, See https://jakearchibald.com/2020/css-paint-predictably-random/ for details.	`0`

💡 The Worklet provides default values so defining them is not required

Example

.element {
  --min-extra-points: 0;
  --max-extra-points: 1;
  --min-randomness: 50;
  --max-randomness: 50;
  --min-size: 20;
  --max-size: 200;
  --num-blobs: 20;
  --offset-x: 0;
  --offset-y: 0;
  --seed: 1234;
  --colors: #71a7ee, #7940c1, #f0e891;
  --min-opacity: 0.1;
  --max-opacity: 0.5;
  background: paint(blobs);
}

Registering the Custom Properties

To properly animate the Custom Properties and to make use of the built-in syntax validation you need to register the Custom Properties. Include this CSS Snippet to do so:

@property --colors {
  syntax: "<color>#";
  initial-value: #71a7ee, #7940c1;
  inherits: false;
}

@property --min-extra-points {
  syntax: "<number>";
  initial-value: 0;
  inherits: false;
}

@property --max-extra-points {
  syntax: "<number>";
  initial-value: 1;
  inherits: false;
}

@property --min-size {
  syntax: "<number>";
  initial-value: 20;
  inherits: false;
}

@property --max-size {
  syntax: "<number>";
  initial-value: 200;
  inherits: false;
}

@property --num-blobs {
  syntax: "<number>";
  initial-value: 20;
  inherits: false;
}

@property --offset-x {
  syntax: "<number>";
  initial-value: 0;
  inherits: false;
}

@property --offset-y {
  syntax: "<number>";
  initial-value: 0;
  inherits: false;
}

@property --seed {
  syntax: "<number>";
  initial-value: 123;
  inherits: true;
}

@property --min-opacity {
  syntax: "<number>";
  initial-value: 0.1;
  inherits: false;
}

@property --max-opacity {
  syntax: "<number>";
  initial-value: 0.5;
  inherits: false;
}

💡 Inclusion of this code snippet is not required, but recommended.

Demo / Development

You can play with a small demo on over at https://css-houdini-blobs.vercel.app/L

If you've cloned the repo you can run npm run demo to launch the included demo.

Acknowledgements

Inspired heavily by css-houdini-circles by @bramus & made blobby by blobs.

Bramus' acknkwledgements: The structure of this project was borrowed from The lines PaintWorklet by @nucliweb. More inspiration was fetched from extra.css by @una

License

css-houdini-blobs is released under the MIT public license. See the enclosed LICENSE for details.

bramus/css-houdini-blobs