movinwords v1.6.4

Movinwords

Movinwords is a versatile plugin for animating sentences, words, and letters in various creative ways.

Playgrounds

Explore Movinwords capabilities in the Playground.

Movinwords is also available for your favorite Frameworks!

Installation

Install Movinwords using npm or yarn:

npm install movinwords
# npx movinwords
# pnpm add movinwords
# yarn add movinwords

Basic Usage

HTML

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

<!-- Dynamically provided sentence -->
<h1 class="my-dynamic-sentence"></h1>
<!-- <h1 id="my-dynamic-sentence"></h1> -->

JavaScript & CSS

Using a Framework or Bundler

import Movinwords from 'movinwords';
import 'movinwords/styles';

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

const dynamicSentence = new Movinwords({
  el: '.my-dynamic-sentence',
  sentence: 'I am a dynamic sentence!',
});

Using 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-dynamic-sentence',
      sentence: 'I am a dynamic sentence!'
    });
  })();
</script>

Options

Customize Movinwords with various configuration options:

Methods

Movinwords provides methods for additional control:

Events

Movinwords emits events at key points in its lifecycle. Use these events to implement custom behavior:

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)
    },
    destroy: (options) => {
      console.log('Instance destroyed!', options)
    }
  }
})

Events and Transitions:

wordTransitionStart and wordTransitionEnd use JavaScript's transitionstart and transitionend events under the hood to determine when they need to fire. These events are triggered 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 property name you want to focus on (e.g., 'filter') and excludes all other properties:

.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.

However, you can override this behavior 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
})

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

Pause

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

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

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

Internally, Movinwords will pause the CSS properties listed in pausableProps. By default, all transitions provided by Movinwords target the opacity and transform properties.

If you create custom transitions that target other CSS properties, ensure to include them in pausableProps.

const mw = new Movinwords({
  el: '.my-sentence',
  autostart: false,
  transition: 'customTransition',
  pausableProps: ['backgroundColor'] // Will pause the background-color property defined in 'customTransition' when pause() is triggered
})

mw.start()
setTimeout(() => mw.pause(), 2000)

Resume

To resume (unpause) the animation, simply call the resume() method:

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

mw.start() // Triggers start
setTimeout(() => mw.pause(), 2000) // Triggers a pause after 2 seconds
setTimeout(() => mw.resume(), 4000) // Resumes the animation after 4 seconds

Destroy

To destroy a Movinwords instance (including events, classes, and other resources), call the destroy() method:

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

mw.start() // Triggers start
setTimeout(() => mw.destroy(), 2000) // Triggers the destroy after 2 seconds

Note: After destroy() completes, each original sentence (or any injected ones) will be restored to their respective container elements.

Initial Delay

You can delay the start of a Movinwords instance by setting the initialDelay property.

const mw = new Movinwords({
  el: '.my-sentence',
  initialDelay: 2000 // Delays the start of Movinwords by 2 seconds.
})

This is similar to doing:

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

setTimeout(() => mw.start(), 2000) // Delays the start of Movinwords by 2 seconds

Transitions

Movinwords comes with the following CSS transitions for use:

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

Offset

You can define an offset value for use with the slide and reveal animations. This value determines how far the words should be offset from the baseline anchor point (0px).

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

})

Reverse Transition

You can reverse the transition animations. This instructs Movinwords to execute the reversed version of the transition you have defined.

Note: This property may make transition names seem counterintuitive, as "In" transitions will behave like "Out" transitions.

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 and/or letters appear or disappear. This will instruct Movinwords to transition the words and/or letters in the opposite order (e.g., the last word of the sentence will be the first to transition).

Reverse Words Order

<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)
})

Reverse Letters Order

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

new Movinwords({
  el: '.my-sentence',
  reverseOrder: true, // "!" will appear first, "d" second, "l" third, etc (From right to left)
  animateLetters: true // Enable letters animation
})

Word Spacing

By default, Movinwords calculates the space between words based on the sentence's font size. However, you can provide your own value to override this default behavior:

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

Letter Spacing

You can specify the space between each letter:

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

Text Alignment

You can set the text alignment for each sentence:

new Movinwords({
  el: '.my-sentence',
  textAlignment: 'left' // Sentences will have their text left aligned
})

Highlight

To highlight words, 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 whether 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 instance 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 individual letter in a word instead, 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
})

Scramble Letters

You can scramble or unscramble the letters in a sentence.

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

new Movinwords({
  el: '.my-sentence',
  scrambleLetters: true, // Enables the scrambler. By default each letter will be unscrambled from gibberish to the final letter
})

You can change the scrambler's mode to scramble the letters:

new Movinwords({
  el: '.my-sentence',
  scrambleLetters: true, // Enables the scrambler
  scrambleMode: 'scramble', // Each letter will scrambled into gibberish
})

Set additional scrambling options to achieve different results:

new Movinwords({
  el: '.my-sentence',
  scrambleLetters: true, // Enables the scrambler
  scrambleChars: '123456789', // A custom set of characters to use for the scrambler
  scrambleFPS: 30, // The scrambler's scrambling speed in FPS
})

You can also combine the scramble options with other Movinwords features for even cooler results:

new Movinwords({
  el: '.my-sentence',
  scrambleLetters: true,
  reverseOrder: true, // The scramble will be done in the letter's opposite direction
  animateLetters: true // The letters will have an animation
})

Like Movinwords, but you want to animate HTML blocks instead?

Try Movinblocks!

It's another lightweight plugin I created, designed for animating divs, headers, footers, sections, buttons, and more in a seamless timeline sequence.

Give it a go!