Menu

Background

Full-frame, responsive image and video backgrounds.

Demos

Image

Create a new Background by passing the source image URL at initialization.

<div class="background js-background" data-background-options='{
  "source": "//spaceholder.dev/1600x900/1.jpg",
  "alt": "Background Image"
}'>
  <h1>Lorem Ipsum</h1>
</div>
import { Background, Utils } from 'formstone';

Utils.ready(() =&gt; {
  Background.construct('.js-background');
});
.background {
  aspect-ratio: 16/9;
  display: grid;
  align-items: center;
  justify-content: center;
}

.background h1 {
  z-index: 1;
  color: white;
  background: rgba(0, 0, 0, 0.7);
  font-size: 40px;
  line-height: 1;
  padding: 20px 30px;
  text-transform: uppercase;
}

Responsive

Create a responsive-friendly Background by defining key/value pairs containing the min-width and image URLs.

<div class="background js-background" data-background-options='{
  "source": {
    "0": "//spaceholder.dev/800x450/1.jpg",
    "740": "//spaceholder.dev/1600x900/3.jpg"
  },
  "alt": "Background Image"
}'>
  <h1>Lorem Ipsum</h1>
</div>
import { Background, Utils } from 'formstone';

Utils.ready(() =&gt; {
  Background.construct('.js-background');
});
.background {
  aspect-ratio: 16/9;
  display: grid;
  align-items: center;
  justify-content: center;
}

.background h1 {
  z-index: 1;
  color: white;
  background: rgba(0, 0, 0, 0.7);
  font-size: 40px;
  line-height: 1;
  padding: 20px 30px;
  text-transform: uppercase;
}

Video

Create a video Background by defining proper browser-specific source video URLs, as well as a poster image URL.

<div class="background js-background" data-background-options='{
  "source": {
    "webm": "//spaceholder.dev/video/video.webm",
    "mp4": "//spaceholder.dev/video/video.mp4",
    "ogg": "//spaceholder.dev/video/video.ogv",
    "poster": "//spaceholder.dev/video/poster.jpg"
  },
  "alt": "Background Video"
}'>
  <h1>Lorem Ipsum</h1>
</div>
import { Background, Utils } from 'formstone';

Utils.ready(() =&gt; {
  Background.construct('.js-background');
});
.background {
  aspect-ratio: 16/9;
  display: grid;
  align-items: center;
  justify-content: center;
}

.background h1 {
  z-index: 1;
  color: white;
  background: rgba(0, 0, 0, 0.7);
  font-size: 40px;
  line-height: 1;
  padding: 20px 30px;
  text-transform: uppercase;
}

YouTube

Create a YouTube Background by defining the youtube URL.

<div class="demo_background js-background" data-background-options='{
  "source": {
    "youtube": "https://www.youtube.com/watch?v=ScMzIvxBSi4"
  }
}'>
  <h1>Lorem Ipsum</h1>
</div>
import { Background, Utils } from 'formstone';

Utils.ready(() =&gt; {
  Background.construct('.js-background');
});
.demo_background {
  aspect-ratio: 16/9;
  display: grid;
  align-items: center;
  justify-content: center;
}

.demo_background h1 {
  z-index: 1;
  color: white;
  background: rgba(0, 0, 0, 0.7);
  font-size: 40px;
  line-height: 1;
  padding: 20px 30px;
  text-transform: uppercase;
}

Options

Set instance options by passing a valid object at initialization, or to the public .defaults() method. Custom options for a specific instance can also be set by attaching a data-background-options attribute containing a properly formatted JSON object to the target element.

Name Type Default Description
alt string '' Image alt attribute
autoPlay boolean true Autoplay video
lazy boolean false Lazy load media on scroll
lazyOffset string '100px' Distance from bottom of window for lazy loading
loop boolean true Loop video
mute boolean true Mute video
source string | object null Source image URL (string or responsive object) or video object
youtubeOptions object {} Options passed to YouTube player

Data attributes provide configuration options and can be set directly on the target element.

Name Type Description
data-background-options string (JSON) JSON encoded object containing instance options

Methods

Methods are publicly available to all active instances, unless otherwise stated.

Name Description
.construct() Initializes Background plugin on target elements
.defaults() Sets default options for future Background instances
.destroy() Removes plugin and all related data
.load() Loads new source media
.mute() Mutes current video
.pause() Pauses current video
.play() Plays current video
.unmute() Unmutes current video

.construct()

Initializes Background plugin on target elements.

Parameters

Name Type Default Description
selector string (required) '' Selector string to target
options object (optional) {} Object containing instance options

Returns

Type Description
NodeList NodeList of target elements

Examples

let targets = Background.construct('.js-background');
let targets = Background.construct('.js-background', {
  lazy: true,
  lazyOffset: '10vh'
});

.defaults()

Sets default options for future Background instances.

Parameters

Name Type Default Description
options object (required) {} Object containing default options

Examples

Background.defaults({
  lazy: true,
  lazyOffset: '10vh'
});

.destroy()

Removes plugin and all related data.

Examples

el.Background.destroy();

.load()

Loads new source media.

Parameters

Name Type Default Description
source string | object (required) null Source image URL (string or responsive object) or video object

Examples

// Load single image
el.Background.load('/path/to/image.jpg');
// Load responsive images
el.Background.load({
  0: '/path/to/small-image.jpg',
  740: '/path/to/large-image.jpg'
});
// Load video
el.Background.load({
  mp4: '/path/to/video.mp4',
  webm: '/path/to/video.webm',
  poster: '/path/to/poster.jpg'
});
// Load YouTube video
el.Background.load({
  youtube: 'https://www.youtube.com/watch?v=VIDEO_ID'
});

.mute()

Mutes current video.

Examples

el.Background.mute();

.pause()

Pauses current video.

Examples

el.Background.pause();

.play()

Plays current video.

Examples

el.Background.play();

.unmute()

Unmutes current video.

Examples

el.Background.unmute();

Events

Events are triggered on the target instance's element, unless otherwise stated.

Name Description
background:loaded Background media loaded

Styles

CSS custom properties are used to modify default styles.

Property Default Description
--fs-background-duration 0.15s Transition duration

Classes allow deeper customization and indicate the current state of a specific instance.

Classname Type Description
.fs-background element Target element
.fs-background-container element Media container element
.fs-background-media element Media element
.fs-background-image modifier Indicates image media
.fs-background-video modifier Indicates video media
.fs-background-embed modifier Indicates embeded media (YouTube)
.fs-background-loaded modifier Indicates media has loaded
.fs-background-lazy modifier Indicates lazy loading media