bRando.js

Website background randomizer

Automatically change CSS backgrounds on any DOM element in a random or sequential order.

📖 Readme
📓 API documentation

Created by yak

Demo

Intro

Would you like to...

Randomly change backgrounds on your website?
Smoothly rotate through a collection of CSS background images, colors, and/or gradients?
Change backgrounds on 1337 elements simultaneously?! (not recommended but doable 😂)
Impress your website visitors?

Try out bRando.js!

The bRando.js library lets you specify what HTML element(s) to add a background changer to, what CSS backgrounds to use, and more. It is usable in the browser and more environments are coming soon.

Installation

There are a couple different ways to add this library:

CDN

Skip the download, include the following code in your HTML right before </head>:

<script src="https://unpkg.com/brandojs/dist/bRando.js"></script>

Manual Download

Download the file, and include the following code in your HTML right before </head>:

<script src="./your/scripts/path/bRando.js"></script>

Of course, make sure the path points to where you put the script.

Verifying Installation

To test that the library is installed correctly, create a demo instance with the following code by placing it right before your page's </body> tag:

<script>
    const demo = bRando.create(); // creates a demo background changer
</script>

This will create a background changer with demo backgrounds on the <body> element. You should see something like this behind the main content:

demo screencap

Usage

Create a new background changer by calling the create() function from the bRando library and passing it an options object containing the desired settings.

const options = {
    CSSSelector: "main", // A CSS selector
    // An array of CSS backgrounds
    backgrounds: [
        "aqua", // solid color
        "linear-gradient(80deg, #0864c8 25%, #588fca 75%)", // gradient
        `url("somewhere/some-image.jpg") center/cover no-repeat`, // image
        `center / contain no-repeat url("../../media/examples/firefox-logo.svg"),
        #eee 35% url("../../media/examples/lizard.png")`, // everything
    ],
    timeout: 5000, // The time between background changes in milliseconds
    random: true, // Whether to rotate through the backgrounds randomly or not
    transition: "500ms ease-in", // A CSS transition to be used when changing between backgrounds
};

const bgChanger = bRando.create(options); // create background changer with the options set above

// call next() if you want the page to load with one of the backgrounds immediately
bgChanger.next(); // remove this line if you want a smooth first transition

All options are optional and have default values if they are not included in the options object.

Learn how to control the background changer that is returned by referring to the bRando class documentation.

ℹ️ Preload Images

Be sure to preload any images used as backgrounds before creating the background changer or your end user may see partially loaded background images. There are a few ways to do this. For example, you could add preload <link> tags in the <head> of your document:
<link rel="preload" href="some-image-used-as-a-background1.jpg" as="image" />
<link rel="preload" href="some-image-used-as-a-background2.jpg" as="image" />
<link rel="preload" href="some-image-used-as-a-background3.jpg" as="image" />

⚠️ Optimize Images

Always optimize any images used as backgrounds to minimize the chance that your end user sees partially loaded background images. Use something like imagecompressor.com which allows you to adjust quality settings and a compression level for each image.