Skip to content

Do you find web animations distracting? Togglific provides a distraction-free web experience!

License

Notifications You must be signed in to change notification settings

svinkle/togglific

Repository files navigation

Build Status npm version

Togglific

Enjoy a distraction-free web experience!

Toggle web animations on or off; for people with vestibular disorders, who are prone to motion sickness, or who find animations distracting!

Features

The following animated elements will paused on button click:

  • CSS Animations (animation and transform properties)
  • JavaScript Animations (requestAnimationFrame() method)
  • SVG animations
  • jQuery animations
  • Animated .gif and .webp images
  • HTML <video> elements
  • Targets same-domain <iframe> elements for all of the above

Demo

Check out the demo section to see Togglific in action!


Products

Togglific generates three separate products:

  1. Stand-alone script: For development teams to implement into their own projects and setup custom controls. This covers all animations.

    See the script options for more details on how to customize for your own needs!

  2. Bookmarklet: For anyone wishing to quickly pause animations on the current page their viewing.

    The bookmarklet also covers all animations and has the greatest browser support.

    Note: State does not persist; the user needs to click the bookmarklet control on each page load to pause animations.

  3. Browser extension: Available for Chrome and Firefox.

    With this, localStorage is used to persist the selection. The user only has to click the button once to always disable animations for the current domain.

    Note: At this time, the extension does not toggle JavaScript based animations due to technical limitations.

Let's look at each in more detail:

Stand-alone script

Usage

  1. Include the lib at the bottom of your page:
<script src="dist/stand-alone/togglific.js"></script>
  1. Create a new instance and supply the id of your toggle button:
<script>
  new Togglific.Togglific([options], 'toggler');
</script>

See script options for more info on the [options] parameter.

  1. Add the toggle button to your HTML:
<button id="toggler">Toggle Animations!</button>

npm Package

You can also grab the stand-alone script and include it into your project via npm!

Installation
npm install togglific
Usage
  1. In your JavaScript file…
const toggler = require('togglific');
// …
new toggler.Togglific([options], 'toggler');
  1. Then add a <button> element as a toggle.
<button id="toggler">Toggle Animations!</button>

Bookmarklet

Simply drag the Bookmarklet! link to your bookmarks bar in your browser and you're all set!

Browser extensions

Install the browser extension from one the following browser vendor plugin repositories!

Chrome

Install the browser extension from the Chrome Web Store!

Firefox

Install the browser extension from Firefox Add-ons!

Edge

Install the browser extension from the Microsoft Store!

Coming soon!


Script Options

The stand-alone script accepts options when using the script on your page or website.

Options are sent in the format of an object literal to the Togglific instance as the first parameter.

There are a few things you can set for options, including:

Custom CSS

If you want to customize, you can pass specific CSS to the object. By default, this CSS would be applied to all elements:

new Togglific.Togglific(
  {
    css: {
      height: 'auto',
      padding: '10px'
    }
  },
  'toggler'
);

Specify your own selectors

If you want only specific elements to be effected, you can add CSS selectors as a string:

new Togglific.Togglific(
  {
    selectors: 'section, .content'
  },
  'toggler'
);

Combine both options, Custom CSS and Specify your own Selectors to have specific elements only be effected with the desired CSS.

Exclude modules

By default, all components are included for toggling animations. If you'd prefer to remove a specific component to always allow animations, you can set it to be excluded.

For example, to exempt CSS and jQuery:

new Togglific.Togglific(
  {
    modules: {
      css: false,
      jquery: false
    }
  },
  'toggler'
);

Default options

To leave everything as-is and accept all components, set the instance [options] parameter to null.

new Togglific.Togglific(null, 'toggler');

Contributing

Contributions are always welcome! Please read the Contributing document if you'd like to help out with the project.

License

This project and its source code is licensed under the MIT license.