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:

Option	Type	Default	Description
el	string	null	Required: The element containing the sentence.
sentence	string	''	The sentence to animate dynamically.
initialDelay	number	0	The delay before animation starts, in milliseconds (See Initial Delay)
duration	number	1000	The duration of the animation, in milliseconds.
delay	number	100	The delay between word/letter animations, in milliseconds.
offset	number	20	The offset for slide/reveal transitions (See Offset).
reverseTransition	boolean	false	If true, reverses the animation transition (See Reverse Transition).
reverseOrder	boolean	false	If true, reverses the order of word/letter animations (See Reverse Order).
animateLetters	boolean	false	If true, animates individual letters (See Animate Letters).
autostart	boolean	true	If true, starts the animation on instance creation (See Autostart).
transition	MwTransition	fadeIn	The transition effect to apply (See Transitions).
pausableProps	MwCSSProperties[]	['opacity', 'transform']	CSS properties to pause when animation is paused (See Pause).
wordSpacing	number	null	Custom spacing between words (in pixels) (See Word Spacing).
letterSpacing	number	null	Custom spacing between letters (in pixels) (See Letter Spacing).
highlight	MwHighlightOptions	{ classname: 'highlight', tag: 'strong', words: [] }	Configuration to highlight specific words.
textAlignment	MwTextAlignment	initial	The alignment of text inside the sentence (e.g., left, center, right).
events	MwEventListeners	{}	Callbacks for lifecycle events like start, pause, or end.
eventsTransitionProperty	string	opacity	The CSS property used to control transition-related events.
scrambleLetters	boolean	false	Enables the scrambling or unscrambling of letters in the sentence (See Scramble Letters).
scrambleMode	MwScrambleMode	unscramble	The mode for scrambling letters (e.g., scramble, unscramble) (See Scramble Letters).
scrambleChars	string	ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789	The characters used during the scrambling process (See Scramble Letters).
scrambleFPS	number	16	The frames per second for the scrambling animation (See Scramble Letters).
intersectionStart	boolean	false	Starts the animation when the element intersects the viewport (See Viewport Intersection).
intersectionOptions	MwIntersectionObserverProperties	{ root: null, threshold: 0, rootMargin: '0px' }	Configuration for the viewport intersection behavior (See Viewport Intersection).

Methods

Movinwords provides methods for additional control:

Method	Description
start	Starts the animation (See Autostart).
pause	Pauses the animation (See Pause).
resume	Resumes the animation (See Resume).
destroy	Destroys the instance and cleans up all associated resources (See Destroy).

Events

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

Event Name	Description
start	Triggered when the animation starts.
end	Triggered when the animation ends.
pause	Triggered when the animation is paused.
resume	Triggered when the animation is resumed.
destroy	Triggered when the instance is destroyed.
wordTransitionStart	Triggered at the start of a word transition.
wordTransitionEnd	Triggered at the end of a word transition.
scrambleStart	Triggered when the letters scrambler starts.
scrambleEnd	Triggered when the letters scrambler ends.
letterScrambleStart	Triggered when a letter scrambling starts.
letterScrambling	Triggered when a letter scrambles.
letterScrambleEnd	Triggered when a letter scrambling ends.

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:

Name	Effect
fadeIn	Words fade in
slideInTop	Words slide+fade in from top to bottom
slideInBottom	Words slide+fade in from bottom to top
slideInLeft	Words slide+fade in from left to right
slideInRight	Words slide+fade in from right to left
revealInTop	Words slide+fade in from top to bottom inside a hidden container
revealInBottom	Words slide+fade in from bottom to top inside a hidden container

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

Options	Type	Default	Description
classname	string	highlight	Class name to append to the highlighted word tags
tag	string	strong	HTML tag to wrap the highlighted word
words	array	[]	Array containing the words to highlight

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!