README
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);