@timbroddin/css-houdini-blobs

CSS Houdini Background Blobs

Usage no npm install needed!

<script type="module">
  import timbroddinCssHoudiniBlobs from 'https://cdn.skypack.dev/@timbroddin/css-houdini-blobs';
</script>

README

CSS Houdini Blobs

A CSS Houdini Paint Worklet to draw blobs.

CSS Houdini 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/css-houdini-circles/dist/circles.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.