movinwords v1.5.0

movinwords

A plugin to animate sentences, words and letters.

Playground

Check out the playground here.

Installation

npm install movinwords

or

yarn add movinwords

Basic Usage

HTML

<!-- Get Movinwords to animate a given sentence -->
<h1 class="my-sentence">I am an animated sentence.</h1>

<!-- Or you can provide the sentence dynamically (see below) -->
<h1 class="my-injected-sentence"></h1>

JS & CSS

With a bundler

import Movinwords from 'movinwords';
import 'movinwords/movinwords.css';

const sentence = new Movinwords({
  el: '.my-sentence'
});

const injectedSentence = new Movinwords({
  el: '.my-injected-sentence',
  sentence: 'Hello world, I am a sentence!'
});

From a CDN

<link rel="stylesheet" href="https://unpkg.com/movinwords/dist/movinwords.css">
<script src="https://unpkg.com/movinwords/dist/movinwords.min.js"></script>

<script>
  (function () {
    const sentence = new Movinwords({
      el: '.my-sentence'
    });

    const injectedSentence = new Movinwords({
      el: '.my-injected-sentence',
      sentence: 'Hello world, I am a sentence!'
    });
  })();
</script>

Instance Options

Methods

Events

You can register events callbacks to be fired at different points of Movinword's lifecycle.

const mw = new Movinwords({
  el: '.my-sentence',
  events: {
    start: (options) => {
      console.log('Started!', options)
    },
    wordTransitionStart: (options) => {
      console.log('Word Transition Started', options)
    },
    wordTransitionEnd: (options) => {
      console.log('Word Transition Ended', options)
    },
    end: (options) => {
      console.log('Ended!', options)
    }
  }
})

Events and Transitions:

wordTransitionStart and wordTransitionEnd use Javascript's transitionstart and transitionend events under the hood to know when they need to fire. These last two fire for each CSS transition property declared (e.g: If a CSS transition uses opacity and transform, the events will fire twice).

To avoid this issue we have exposed the eventsTransitionProperty property. It expects the CSS transition name you want to use as 'filter' to focus on and exclude all other props:

.mw.slideInBottom .mw-l {
  opacity: 0;
  transition-property: opacity, transform;

const mw = new Movinwords({
  el: '.my-sentence',
  transition: 'slideInBottom',
  events: { [YOUR EVENT CALLBACKS ] },
  eventsTransitionProperty: 'opacity' // Movinwords will focus on the opacity prop and ignore the transform one.
})

Autostart

By default Movinwords will start as soon as you create the instance. But you can override this action and trigger the start action manually by passing autostart: false in the instance options, and using the start() method:

const mw = new Movinwords({
  el: '.my-sentence',
  autostart: false
})

// Triggers start after 2 seconds.
setTimeout(() => {
  mw.start()
}, 2000)

Pause

To pause an animation you can call the pause() method:

const mw = new Movinwords({
  el: '.my-sentence',
  autostart: false
})

// Triggers start.
mw.start()

setTimeout(() => {
  // Triggers a pause after 2 seconds.
  mw.pause()
}, 2000)

Internally Movinwords will pause those css properties provided in pausableProps. By default, all transitions shipped with Movinwords target the opacity and transform css properties.

If you create custom transitions which target other css properties, be sure to provide them through pausableProps.

Resume

To resume (unpause) the animation you need to call the resume() method:

const mw = new Movinwords({
  el: '.my-sentence',
  autostart: false
})

// Triggers start.
mw.start()

setTimeout(() => {
  // Triggers a pause after 2 seconds.
  mw.pause()
}, 2000)

setTimeout(() => {
  // Resumes the animation after 4 seconds.
  mw.resume()
}, 4000)

Transitions

Movinwords ships with these css transitions to use:

new Movinwords({
  el: '.my-sentence',
  transition: 'slideInLeft' // Words will slide from the left
})

Offset

You can define an offset value to be used with slide and reveal animations. This will tell Movinwords how offsetted the words should be from the baseline anchor point (0px).

new Movinwords({
  el: '.my-sentence',
  transition: 'slideInLeft',
  offset: 50 // Words will be 50px offset from the start (0px) and slide in from left to right
})

Reverse Transition

You can reverse the transition animations. This will tell Movinwords to execute a reversed version of the transition you have defined. Note: this property makes the transition names counterintuitive, as "In" transitions behave like "out" ones.

new Movinwords({
  el: '.my-sentence',
  transition: 'fadeIn',
  reverseTransition: true // Transition "fadeIn" will behave like a "fade out" (from opacity 1, to opacity 0).
})

Reverse Order

You can reverse the order in which the words appear/disappear. This will tell Movinwords to transition the words the opposite order (Last word of the sentence is the first to transition).

<h2 class="my-sentence">Hello lovely world!</h2>

new Movinwords({
  el: '.my-sentence',
  reverseOrder: true // "world!" will appear first, "lovely" second, "Hello" last (From right to left).
})

Word Spacing

By default Movinwords will calculate the space between words based on the sentence's font size, but you can pass a value of your own to override this action:

new Movinwords({
  el: '.my-sentence',
  wordSpacing: 50 // Will set a 50px space between each word.
})

Letter Spacing

You can provide a space between each letter:

new Movinwords({
  el: '.my-sentence',
  letterSpacing: 50 // Will set a 50px space between each letter.
})

Highlight

To highlight words you need to pass a highlight object in the instance options:

<h1 class="my-sentence">Hello world! I am an animated sentence.</h1>

new Movinwords({
  el: '.my-sentence',
  highlight: {
    classname: 'highlight',
    tag: 'strong',
    words: ['world!', 'am']
  }
})

Viewport Intersection

You can define if you want to trigger Movinwords only when the element is in the Viewport.

new Movinwords({
  el: '.my-sentence',
  intersectionStart: true // Movinwords will start when the element enters the viewport.
})

Movinwords uses IntersectionObserver behind the scenes. If you wish to modify the intersection properties you can provide intersectionOptions in the options:

new Movinwords({
  el: '.my-sentence',
  intersectionStart: true,
  intersectionOptions: {
    root: null,
    threshold: 0,
    rootMargin: '0px'
  }
})

Animate Letters

By default Movinwords animates the words in a sentence. If you wish to animate each single letter in a word instead you can set animateLetters to true.

<h2 class="my-sentence">Hello lovely world!</h2>

new Movinwords({
  el: '.my-sentence',
  transition: 'slideInBottom',
  animateLetters: true // Each letter will slide in from the bottom
})