/vi-bg

a library / fork / ever-so-slight adaptation of marvinx-x/cursors-emitter

Primary LanguageJavaScript

🍦 VI-BG / visual ice cream background library

A slick, zero-dependancy interactive SVG visualisation / background for your website. A library / fork / ever-so-slight adaptation of the inspiring marvinx-x/cursors-emitter.

screenshot gallery

Demo - Tap the logo to toggle visualisations

Original article on Codrops - Credit to Marvinx

HTML: Quick start

Include the library as a script, directly on your page:

<script src="//cdn.jsdelivr.net/gh/theprojectsomething/vi-bg/dist/vi-bg.umd.cjs"></script>

Optionally, set configuration options via data attributes:

<script
  data-colour-a=#f0f
  data-colour-b=#ff0
  data-size=1
  data-length=0
  bg=wave
  src="//cdn.jsdelivr.net/gh/theprojectsomething/vi-bg/dist/vi-bg.umd.cjs"
></script>

ESM

Install + import

Use directly via the CDN:

import * as viBg from "https://cdn.jsdelivr.net/gh/theprojectsomething/vi-bg/dist/vi-bg.js"

Or install:

npm i --save https://github.com/theprojectsomething/vi-bg/tarball/master

and local import:

import * as viBg from "vi-bg"

Usage in a module

Unlike script tag usage, the library must be initialised when used inside a module:

viBg.init({
  bg: 'wave',
  colourA: "#f0f",
  colourB: "#ff0",
  size: 1,
  length: 0,
});

Available methods:

  • init ( config?: object ) => void
    Initialises the visualisation, optionally accepts a configuration object (see below for options)
  • pause ( ) => void
    Pauses the animation
  • play ( ) => void
    Plays the animation
  • paused ( ) => true | false
    Returns true if the animation is paused
  • setConfig ( config: object ) => void
    Updates the current configuration on the fly or prior to initialisation. Pass an empty object to clear the current config
  • getConfig ( ) => config: object
    Returns the current parsed configuration. Prior to initialisation this will only include options that have been set with setConfig()
  • getDefaultConfig ( bg?: string = trail | tube | wave ) => config?: object
    Returns the default configuration for the provided background name. If no name is provided and the visualisation has been initialised, returns the default configuration for the active background
  • destroy ( ) => void
    Removes the visualisation, including all dom elements and event listeners

Configuration

Configuration options can be set on script tags via data attributes, see the HTML: Quick start. For ESM usage, configuration should be set via either the init() or setConfig() methods, see ESM: Available methods.

  • bg: string = trail | tube | wave
    Defines the visualisation to show
  • colourA: string = #e3a6f8
    One of two colours. Accepts any valid colour string, including hex, rgb, shorthand and alpha variations
  • colourB: string = #82f8d9
    One of two colours. Accepts any valid colour string, including hex, rgb, shorthand and alpha variations
  • size: number = [0-3] (default value varies per visualisation)
    Controls one visual dimension; usually a width or radius. Effect varies per visualisation
  • length: number = [0-3] (default value varies per visualisation)
    Controls one visual dimension. Effect varies per visualisation
  • taper: number = [0-3] (default value varies per visualisation)
    Controls one visual dimension, usually a density or a delta. Effect varies per visualisation
  • invert: boolean = false
    Reverses the order of the animation. Effect varies per visualisation
  • xStart: number = 0.5 [-0.5→1.5]
    The starting position of the center of the visualisation, as a ratio of the width of its container (see below). Values smaller than 0 or larger than 1 will position the visualisation outside of the visible container
  • yStart: number = 0.5 [-0.5→1.5]
    The starting position of the center of the visualisation, as a ratio of the height of its container (see below). Values smaller than 0 or larger than 1 will position the visualisation outside of the visible container.
  • paused: boolean = false
    Use this option to initialise the visualisation in a paused state so it doesn't respond to pointer events
  • container: CSS selector | Element = document.body
    By default the visualisation will render directly into the body and respond to pointer events on the window. To render the visualisation within a custom container, supply a CSS selector or DOM node.

Notes:

  • options are listed above in camel case (suitable for ESM usage). When configuring via data attributes, options should be converted to kebab case, e.g: colourA => data-colour-a
  • currently only one visualisation can be rendered on the page at a time

Credits

License

MIT