brandojs

v1.1.6

Published

a year ago

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

Downloads

0High
0Medium
0Low

CSS background randomizer background changer background property background-image background-color background rotator color changer randomizer random sequential javascript typescript

➤ Table of Contents

➤ 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.

➤ Approach

bRando.js utilizes the pseudo-element ::after and CSS custom properties (variables) to facilitate smooth transitions. Background changer instances follow this approach:

Create an ::after style definition with CSS variables and the chosen transition settings in order to update ::after backgrounds.
Set subsequent backgrounds on the selected element(s) and corresponding ::after('s) in an alternating manner.
Toggle the opacity of the ::after element(s) to switch between the ::after background and element background.

➤ 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:

➤ 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.

➤ API Documentation

Full documentation

➤ To-Do

Planned

Features and fixes planned for development.

Create React component

Ideas

Ideas I have thought up but will not add unless requested.

Add event hooks:
- onChange()
- afterChange()
Add previous()

Have a feature request? Create a new issue and select the "Feature request" type OR write the feature yourself and create a pull request.

➤ Issues

Found a 🐛? Create a new issue or propose a fix by creating a pull request.

➤ License

Licensed under MIT.