Wondering what’s next for npm?Check out our public roadmap! »


    1.0.5 • Public • Published

    CSS Houdini Circles

    A CSS Houdini Paint Worklet to draw background circles.

    CSS Houdini Circles


    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) {

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

    if ('paintWorklet' in CSS) {

    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.

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

    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);


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

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

    .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;
        background-image: paint(circles);
    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


    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.


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


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


    npm i css-houdini-circles

    DownloadsWeekly Downloads






    Unpacked Size

    6.91 kB

    Total Files


    Last publish


    • avatar