zlo2k / shuffle-letters

A JavaScript library to shuffle the text content of a DOM element with an animated effect.

shuffle-letters.js

A JavaScript library to shuffle the text content of a DOM element with an animated effect.

NOTE: This library is a port to vanilla JavaScript of the Shuffle Letters Effect jQuery plugin.

Demo

Check here for a live demo.

Install

$ npm install shuffle-letters --save

Usage

The library is exported in UMD, CommonJS, and ESM formats. You can import it the following ways:

Using ESM import statement

import shuffleLetters from 'shuffle-letters';

Using CommonJS require statement

const shuffleLetters = require('shuffle-letters');

// If you use a bundler like Webpack, you may need to import it the following way 
// as it might try to use the ESM module instead of the CommonJS.
const shuffleLetters = require('shuffle-letters').default;

Old school browser global

<script src="https://unpkg.com/shuffle-letters"></script>

API

shuffleLetters(element, [config])

Params

Param	Type	Default	Description
element	HTMLElement		The HTML element whose textContent we want to apply the shuffle effect.
[config]	object	{}	Configurable object to override the default options.
[config.text]	string	"''"	Alternative text that can be used instead of the textContent of the element.
[config.iterations]	number	8	The number of times the characters will be shuffled before the animation ends.
[config.fps]	number	30	The amount of frames per second that the animation runs.
[config.onComplete]	function	() => void	A callback function that is called when the animation of the effect is complete.

Returns: function - Returns a function that when called, it clears the timeoutID which identifies the timer created by the call to setTimeout() that is used internally for the shuffle effect. Useful for cleanup purposes, for example when you want to remove the element before the animation is completed.

Usage examples

Example 1 - Default options

HTML

<h1>This is a funcy title</h1>

JavaScript

  shuffleLetters(document.querySelector('h1'));

Example 2 - Custom options

HTML

<h1>This is a funcy title</h1>

JavaScript

shuffleLetters(document.querySelector('h1'), {
  text: 'Yet another funcy title',
  iterations: 12,
  fps: 60,
  onComplete: el => {
    console.log('Effect was completed.');
    console.log(el);
  }
});

Example 3 - Shuffle many elements

HTML

<ul>
  <li>List item 1</li>
  <li>List item 2</li>
  <li>List item 3</li>
  <li>List item 4</li>
</ul>

JavaScript

const list = document.querySelector('ul');
const listItems = list.querySelectorAll('li');

Array.prototype.forEach.call(listItems, (element, index) => {
  shuffleLetters(element, {
    onComplete: elm => {
      if (index === listItems.length - 1) {
        console.log('All effects were completed');
      }
    }
  });
});

Example 4 - Cleanup

HTML

<h1>This is a funcy title</h1>

JavaScript

  const clearShuffleLetters = shuffleLetters(document.querySelector('h1'), {
    iterations: 200
  });
  
  // Cleanup after 1 second
  setTimeout(() => clearShuffleLetters(), 1000);

License

The MIT License (MIT)