v1.0.27
Immerse.jsBuild immersive, media driven web experiences - the easy way.
Immerse.js offers a javascript framework for building complex, media-driven web experiences.
Checkout the official plugin website, the Learn to Surf example or the full documentation.
Getting Started
Download the zip or install Immerse.js via NPM.
npm install immersejs
Include dependencies:
<!-- JQuery --><!-- GSAP TweenMax --><!-- GSAP ScrollTo Plugin -->
Include Immerse.js:
<!-- Immerse.js --><!-- Immerse.css -->
Basic Setup
Build HTML markup
At its most basic configuration, Immerse.js will build your section based page from simple HTML markup. It will automatically handle scrolling, navigation and loading with just the following code:
<!-- Wrap your page content so it can be hidden before loading --> <!-- Build your page structure with Immerse sections. --> <!-- Navigation will be injected here. --> <!-- Loading overlay displays until the page's assets have fully loaded -->
Setup & initialise Immerse
// Get a handle on the Immerse setup object inside a variable.var page = ; // Add section configuration... // Initialize the pagepage;
Section configuration
Sections can be configured through registering one on the page variable. The following markup is the most basic configuration:
page;
Assets
Immerse requires all media assets to be registered in the Immerse setup object, so the plugin can properly inject them into the DOM and allow easy manipulation of them through the Immerse API.
Defining assets
Define your assets in Immerse setup:
;
Video file types default to mp4, ogv and webm. Loop defaults to true.
Asset preloading
Adding the wait key to any asset will add it to the asset queue for preloading. Immerse will display a loading overlay until all required assets are loaded. Images will be loaded into the browser cache and audio/video will be considered loaded when the HTML5 canplaythrough event is returned.
'videoName': type: 'video' path: 'assets/audio/gnossienne' loop: true wait: true ...
Video
Once a video asset is registered, it can be easily used as a video background for a page section. It's this simple:
<!-- The imm-video element will stretch to any div positioned relatively -->
Immerse.js will manage initialisation, pausing/playing on scroll and resizing of the HTML5 video without the need for any custom code.
Audio
Immerse easily enables the building of complex layered HTML5 audio soundtracks for each section of your page.
Default soundtrack
Add a default soundtrack by defining the audio layers in Immerse setup. The volume of each individual audio layer can be controlled, along with the length of time it takes for the track to fade out/in when the soundtrack changes.
;
If no default soundtrack is defined, sections without specific audio defined will be silent.
Section-based soundtrack
Soundtracks can also be defined for each section of the page. Inside your Immerse section, just define a new soundtrack and the audio will change to your new soundtrack when the section is scrolled to.
page;
Mute button configuration
Immerse automatically manages any mute buttons with the imm-mute class attached:
The default content of the button is a string - 'Audio On' and 'Audio Off'. However, custom strings can be added in Immerse setup options. For example, a popular setup is using icon font Fontawesome to graphically illustrate audio state:
;
By default, Immerse uses cookies to set the audio to the state the user last left the page.
Programatically control audio
It's also possible to programmatically control audio state:
page; // Get current statepage; // Mutes audiopage; // Unmutes audio
Animations
One of Immerse's key features is offering a clean, easy to read interface for creating animations and targeting them at devices, breakpoints and runtimes.
Multiple animations can be set on a single DOM element and each animation will be appropriately registered/removed by Immerse.js when its breakpoint declaration is met on window resize.
Configuring animation timelines
Below is the most verbose example of defining and executing one GSAP Timeline in Immerse:
page
For most animations (which run when the section is scrolled to and reset when the section is removed from view), only the timeline function need be defined. Every other value may be left to default.
For more information about using GSAP, visit the official GreenSock Animation Platform website.
Attributes
Section attributes allow for individual values to be changed on a per-section basis and trigger a listenable event when changed. The following example will demonstrate how easy it is to change navigation colour through each section of your site, with just one attribute.
Default attribute value
Add the default attribute value to the Immerse setup:
;
Change the attribute based upon section
In your chosen section, define the new attribute value.
page;
Listen for changes & fire custom code
When the page is scrolled to the chosen section, an event will be triggered. Listen to it and execute your desired code. For example, add a class to your navigation so its CSS styles will change to the desired color.
;
Actions
Immerse also allows for any custom code to be triggered using device and runtime targeting.
page;
Scrolling
Immerse solves many problematic issues related to scrolling with elegant solutions.
Fixed scroll vs free scroll
Immerse infers which sections should be fixed height and which should be free scrolling simply by observing your HTML markup:
<!-- By default, sections are fullscreen fixed scrolling sections --> <!-- However, free scrolling sections can be defined in the markup -->
Not sure what we mean by fixed vs free scroll? Check out the official plugin website for examples.
Responsive scrolling
It's possible to create responsive solutions for fixed scrolling sections by unbinding the scroll at certain breakpoints.
page;
For more information on Immerse breakpoints, click here.
ScrollTo Buttons
Adding buttons which link to other Immerse page sections can be achieved through data tags:
<!-- Pass the id of the section --><button data-imm-scroll-to="foo">Scroll to foo</button> <!-- You can also add either UP or DOWN to go to the next/prev sections. Must be in caps. --><button data-imm-scroll-to="DOWN">Go down a section</button>
Programatically control scrolling
It's also possible to control scrolling programmatically:
page;page;
Modals
Immerse offers support for modal overlays out-of-the-box.
Modal markup
<section> <!-- Open modal button --> <button data-imm-modal-open="modal-name"></button> <!-- Modal markup --> <div data-imm-modal-id="modal-name"> <!-- Button will fire the onConfirm function --> <button data-imm-modal-action="confirm">Confirm</button> <!-- Button will fire the onCancel function --> <button data-imm-modal-action="cancel">Cancel</button> <!-- Button will fire the onClose function --> <button data-imm-modal-action="close">Close</button> </div></section>
Modal options
All modal actions can be overridden on a per-modal basis inside a specific Immerse section:
page;
Or globally inside Immerse setup to set defaults for the whole page:
;
YouTube modals
It's easy to add YouTube modals to your Immerse page. Simply paste a YouTube URL into the imm-modal-open data tag and a YouTube modal will be generated.
<button data-imm-modal-open="https://www.youtube.com/watch?v=XXXXXXXXXXX"></button>
The YouTube modal automatically includes the YouTube iFrame API and handles playing, pausing and restarting of the video on open/close of the modal and at the end of the video.
Further Options
The following options are configured in Immerse setup.
Scroll duration & easing
Immerse.js uses the GSAP ScrollTo Plugin to animate between sections. Therefore, it is possible to tweak the default scroll animation using buttery smooth GreenSock easing.
// new Immerse().setup.optionsscroll: duration: 1 easing: Power4easeOut ...
For more information about GSAP easing, click here.
Hash navigation
By default, Immerse uses history.replaceState to enable hash navigation between page sections. If you don't wish to track state:
// new Immerse().setup.optionshashChange: false ...
Custom breakpoints
Immerse uses breakpoints to allow animations, actions and attributes to be targeted at certain responsive screen sizes. To overwrite the default breakpoints, define a new breakpoints object in Immerse setup:
// new Immerse().setup.optionsbreakpoints: newBreakpoint: 300 mobile: 480 tablet: 768 mdDesktop: 992 lgDesktop: 1200 ...
The default breakpoints are set to match the breakpoint sizes for popular front end framework Bootstrap.
Minimum loading time
Before Immerse's asset queue promise is satisfied, a loading overlay is displayed. This is particularly useful for users on slow connections, but users on fast connections, the loading overlay may only appear for a split section and be perceived as bad UI.
Setting minLoadingTime ensures the loading overlay is displayed for at least x seconds before the page animates in.
// new Immerse().setup.optionsminLoadingTime: 1000 ...
Namespacing
Changing all classes and data tags from using 'imm-' is available:
// new Immerse().setup.optionsnamespace: 'foo' ...
This will ensure, for example:
Warning: All styles defined by Immerse MUST be prepended with the new namespace for Immerse to function. This can be done through find and replace, however Immerse's scss files can be included before minification and the $prefix value changed in style.scss
Development Mode
Development mode logs all changes to animations, attributes and actions. It also logs breakpoint changes on resize. It is turned off by default, but can be turned on using:
// new Immerse().setup.optionsdevMode: true ...
Kill Immerse
It's easy to kill all events attached to an Immerse page. You may need to do this when managing multiple Immerse instances on an asynchronously delivered website.
// Your page variable referencepage;
Custom components
Custom Immerse.js components will be available for anyone to develop in the near future once the API is locked down and documentation is up to speed! Follow @willviles for updates.
Future Developments
✔ Section hash state management.
✔ Set of easily-attachable modal window open/close animations. Inspiration here.
☐ Allow state tracking using history.pushState as well as history.replaceState.
☐ Set of easily-attachable section transitions. Inspiration here.
☐ In time, the project will be moved away from a dependency on jQuery toward pure ECMAScript 6 and be restructured to follow UMD patterns.
Got a feature request? Tweet @willviles or open an issue.
Browser Support
Immerse.js aims to support all major browsers in recent versions:
Firefox 26+, Chrome 30+, Safari 5.1+, Opera 10+, IE 9+
About the Author
I'm Will Viles, a digital creative from Birmingham, UK.
With a degree in marketing and design/development skills, I specialise in developing creative, effective one page scrolling websites. I can offer help, guidance & custom site builds using Immerse.js. Feel free to get in contact.
Check out my website or contact me on Twitter.
License
Immerse.js is dual licensed under the MIT license and GPL. For more information click here.