CSS Houdini Circles

A CSS Houdini Paint Worklet to draw background circles.

Usage

1. Getting `css-houdini-circles`

Using a pre-built hosted version

The easiest way to get css-houdini-circles 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-circles locally using NPM.

npm install css-houdini-circles

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

cd css-houdini-circles
npm install
npm run build

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

2. Loading `css-houdini-circles`

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-circles, use https://unpkg.com/css-houdini-circles/dist/circles.js as the moduleURL.

if ('paintWorklet' in CSS) {
    CSS.paintWorklet.addModule(
        'https://unpkg.com/css-houdini-circles/dist/circles.js'
    );
}

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

if ('paintWorklet' in CSS) {
    CSS.paintWorklet.addModule('url/to/circles.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-circles`

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

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

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-radius	Minimum Radius, minimum circle radius (in pixels)	`10`
--max-radius	Maximum Radius, maximum circle radius (in pixels)	`50`
--min-opacity	Minimum Opacity, minimum circle opacity (as a percentage: 0 – 100)	`10`
--max-opacity	Maximum Opacity, maximum circle opacity (as a percentage: 0 – 100)	`80`
--num-circles	Number of Circles to draw	`5`
--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 {
    --colors: #f94144, #f3722c, #f8961e, #f9844a, #f9c74f, #90be6d, #43aa8b,
        #4d908e, #577590, #277da1;
    --min-radius: 20;
    --max-radius: 100;
    --num-circles: 30;
    --min-opacity: 10;
    --max-opacity: 50;
    --seed: 42;

    background-image: paint(circles);
}

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-radius {
    syntax: '<number>';
    initial-value: 10;
    inherits: false;
}
@property --max-radius {
    syntax: '<number>';
    initial-value: 50;
    inherits: false;
}
@property --min-opacity {
    syntax: '<number>';
    initial-value: 10;
    inherits: false;
}
@property --max-opacity {
    syntax: '<number>';
    initial-value: 80;
    inherits: false;
}
@property --num-circles {
    syntax: '<number>';
    initial-value: 5;
    inherits: false;
}
@property --seed {
    syntax: '<number>';
    initial-value: 0;
    inherits: true;
}

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

Demo / Development

You can play with a small demo on CodePen over at https://codepen.io/bramus/pen/PoGbbzL

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

Acknowledgements

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-circles is released under the MIT public license. See the enclosed LICENSE for details.

npm