Package Exports

brandojs
brandojs/dist/bRando.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (brandojs) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

demo screencap

bRando.js

_{Website background randomizer}

Automatically rotate through CSS backgrounds for any DOM element in a random or sequential order.

Compatibility: ✔️Vanilla JavaScript ❌React.js (Coming soon)
Demo: https://brandojs.isaacyakl.com

_{Created by: yak}

📖 Table of Contents

➤ Table of Contents

➤ Installation
- CDN
- Manual Download
➤ Verifying Installation
➤ Usage
- ℹ️ Preload Images
- ⚠️ Optimize Images
➤ API Documentation
➤ To-Do
➤ Issues
➤ License

➤ Installation

There are a couple different ways to use this library:

CDN

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

<script src="https://unpkg.com/brandojs@latest/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>
    let 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 on the bRando library and passing it an options object containing the desired settings.

let options = {
    CSSSelector: "main", // a valid CSS selector (multiple elements are allowed)
    backgrounds: [
        // valid CSS background properties
        "aqua", // solid color
        "linear-gradient(80deg, #0864c8 25%, #588fca 75%)", // gradient
        `url("somewhere/some-image.jpg") center/cover no-repeat`, // image
        `background: center / contain no-repeat url("../../media/examples/firefox-logo.svg"),
        #eee 35% url("../../media/examples/lizard.png")`, // everything
    ],
    timeout: 5000, // time between changes in milliseconds
    random: true, // whether to go through the backgrounds randomly or not (no two backgrounds are allowed to be back-to-back)
    transition: "500ms ease-in", // a CSS transition property for changing between backgrounds
};

let bgRotator = 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
bgRotator.next(); // remove this line if you want a smooth first transition

All options are optional. Default values and further details for them can be found in the API 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

Features and fixes planned for development.

Complete API documentation
Add console feedback for invalid options
Add event hooks: onChange()
Warn users about setting transition animations time > timeout in both usage section and console
Add previous()
Create React component
Add explanation of how the library works and credit learning sources
Update year date in LICENSE automatically

➤ Issues

Found a 🐛? Create a new issue.

➤ License

Licensed under MIT.