🫧 bubbly-bg

October 29, 2025 · View on GitHub

🫧 bubbly-bg

Beautiful bubbly backgrounds in less than 1kB gzipped

Live Demo

Bubbly animated

✨ Features

🪶 Lightweight - Only 1.6kB minified, 841 bytes gzipped
🎨 Customizable - Full control over colors, gradients, and animations
🚀 Zero dependencies - Pure vanilla JavaScript
📦 Easy to use - Just include and call bubbly()
🎯 TypeScript support - Full type definitions included
🔧 Flexible - Works with your own canvas or creates one automatically

🚀 Quick Start

Add bubbly to your webpage and call bubbly():

<body>
  ...
  <script src="https://cdn.jsdelivr.net/npm/bubbly-bg@1.0.0/dist/bubbly-bg.js"></script>
  <script>bubbly();</script>
</body>

That's it! Bubbly creates a canvas element with position: fixed and z-index: -1, filling the viewport. It's plug-and-play for most projects.

Custom Canvas

You can also use your own canvas element:

bubbly({ canvas: document.querySelector("#my-canvas") });

📦 Installation

CDN

<script src="https://cdn.jsdelivr.net/npm/bubbly-bg@1.0.0/dist/bubbly-bg.js"></script>

npm

npm install bubbly-bg

Direct Download

Download bubbly-bg.js

⚙️ Configuration

All Options

bubbly({
    canvas: document.querySelector("#background"), // default is created and attached automatically
    compose: "lighter", // default is "lighter"
    animate: false, // default is true
    background: (ctx) => "#2AE", // default background, can be a color string or function returning gradient
    bubbles: {
        count: 100, // default is Math.floor((canvas.width + canvas.height) * 0.02)
        radius: () => 4 + Math.random() * 25, // default is () => 4 + Math.random() * window.innerWidth / 25
        fill: () => `hsla(${Math.random() * 360}, 100%, 50%, ${Math.random() * 0.25})`, // default is () => `hsla(0, 0%, 100%, ${Math.random() * 0.1})`
        angle: () => Math.random() * Math.PI * 2, // default is this
        velocity: () => 0.1 + Math.random() * 0.5, // default is this
        shadow: () => ({blur: 4, color: "#fff"}), // default is () => null
        stroke: () => ({width: 2, color: "#fff"}), // default is () => null
        objectCreator: () => ({...}) // advanced: custom bubble object creator
    }
});

Configuration Options

Option	Type	Default	Description
`canvas`	`HTMLCanvasElement`	auto-created	Canvas element to use
`compose`	`string`	`"lighter"`	Global composite operation
`animate`	`boolean`	`true`	Whether to animate bubbles
`background`	`string \| function`	`"#2AE"`	Background color or gradient function
`bubbles.count`	`number`	auto-calculated	Number of bubbles
`bubbles.radius`	`function`	auto-calculated	Function returning bubble radius
`bubbles.fill`	`function`	white with opacity	Function returning bubble fill color
`bubbles.angle`	`function`	random	Function returning movement angle
`bubbles.velocity`	`function`	random	Function returning velocity
`bubbles.shadow`	`function`	`null`	Function returning shadow config
`bubbles.stroke`	`function`	`null`	Function returning stroke config
`bubbles.objectCreator`	`function`	default creator	Advanced: custom bubble creator

🎨 Examples

Default (Blue with white bubbles)

bubbly();

Black/Red with red bubbles

bubbly({
    background: (ctx) => {
        const gradient = ctx.createLinearGradient(0, 0, ctx.canvas.width, ctx.canvas.height);
        gradient.addColorStop(0, "#111");
        gradient.addColorStop(1, "#422");
        return gradient;
    },
    bubbles: {
        fill: () => `hsla(0, 100%, 50%, ${Math.random() * 0.25})`,
        shadow: () => ({blur: 4, color: "#fff"})
    }
});

Purple with multicolored bubbles

bubbly({
    background: (ctx) => {
        const gradient = ctx.createLinearGradient(0, 0, ctx.canvas.width, ctx.canvas.height);
        gradient.addColorStop(0, "#4c004c");
        gradient.addColorStop(1, "#1a001a");
        return gradient;
    },
    bubbles: {
        fill: () => `hsla(${Math.random() * 360}, 100%, 50%, ${Math.random() * 0.25})`,
        shadow: () => ({blur: 4, color: "#fff"})
    }
});

Yellow/Pink with red/orange/yellow bubbles

bubbly({
    background: (ctx) => {
        const gradient = ctx.createLinearGradient(0, 0, ctx.canvas.width, ctx.canvas.height);
        gradient.addColorStop(0, "#fff4e6");
        gradient.addColorStop(1, "#ffe9e4");
        return gradient;
    },
    compose: "source-over",
    bubbles: {
        fill: () => `hsla(${Math.random() * 50}, 100%, 50%, .3)`,
        shadow: () => ({blur: 1, color: "#fff"})
    }
});

🔧 Advanced Usage

Custom Bubble Creator

For complete control over bubble creation and rendering:

bubbly({
    bubbles: {
        objectCreator: function() {
            return {
                x: Math.random() * canvas.width,
                y: Math.random() * canvas.height,
                r: 10,
                a: Math.random() * Math.PI * 2,
                v: 1,
                draw: (ctx, bubble) => {
                    // Custom drawing logic
                    ctx.fillStyle = "red";
                    ctx.fillRect(bubble.x, bubble.y, bubble.r, bubble.r);
                }
            };
        }
    }
});

📝 TypeScript

Full TypeScript definitions are included:

import { bubbly, BubblyConfig } from 'bubbly-bg';

const config: BubblyConfig = {
    animate: true,
    bubbles: {
        count: 50
    }
};

bubbly(config);

📄 License

🤝 Contributing

Contributions, issues and feature requests are welcome!

⭐ Show your support

Give a ⭐️ if this project helped you!

Made with ❤️ by David Åse