1.6.4 • Published 6 months ago

movinwords v1.6.4

Weekly downloads
74
License
MIT
Repository
github
Last release
6 months ago

Movinwords Logo

Movinwords

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

License: MIT npm version

Playgrounds

Explore Movinwords capabilities in the Playground.

Movinwords is also available for your favorite Frameworks!

Vue React Nuxt Next Svelte Angular

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:

OptionTypeDefaultDescription
elstringnullRequired: The element containing the sentence.
sentencestring''The sentence to animate dynamically.
initialDelaynumber0The delay before animation starts, in milliseconds (See Initial Delay)
durationnumber1000The duration of the animation, in milliseconds.
delaynumber100The delay between word/letter animations, in milliseconds.
offsetnumber20The offset for slide/reveal transitions (See Offset).
reverseTransitionbooleanfalseIf true, reverses the animation transition (See Reverse Transition).
reverseOrderbooleanfalseIf true, reverses the order of word/letter animations (See Reverse Order).
animateLettersbooleanfalseIf true, animates individual letters (See Animate Letters).
autostartbooleantrueIf true, starts the animation on instance creation (See Autostart).
transitionMwTransitionfadeInThe transition effect to apply (See Transitions).
pausablePropsMwCSSProperties[]['opacity', 'transform']CSS properties to pause when animation is paused (See Pause).
wordSpacingnumbernullCustom spacing between words (in pixels) (See Word Spacing).
letterSpacingnumbernullCustom spacing between letters (in pixels) (See Letter Spacing).
highlightMwHighlightOptions{ classname: 'highlight', tag: 'strong', words: [] }Configuration to highlight specific words.
textAlignmentMwTextAlignmentinitialThe alignment of text inside the sentence (e.g., left, center, right).
eventsMwEventListeners{}Callbacks for lifecycle events like start, pause, or end.
eventsTransitionPropertystringopacityThe CSS property used to control transition-related events.
scrambleLettersbooleanfalseEnables the scrambling or unscrambling of letters in the sentence (See Scramble Letters).
scrambleModeMwScrambleModeunscrambleThe mode for scrambling letters (e.g., scramble, unscramble) (See Scramble Letters).
scrambleCharsstringABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789The characters used during the scrambling process (See Scramble Letters).
scrambleFPSnumber16The frames per second for the scrambling animation (See Scramble Letters).
intersectionStartbooleanfalseStarts the animation when the element intersects the viewport (See Viewport Intersection).
intersectionOptionsMwIntersectionObserverProperties{ root: null, threshold: 0, rootMargin: '0px' }Configuration for the viewport intersection behavior (See Viewport Intersection).

Methods

Movinwords provides methods for additional control:

MethodDescription
startStarts the animation (See Autostart).
pausePauses the animation (See Pause).
resumeResumes the animation (See Resume).
destroyDestroys 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 NameDescription
startTriggered when the animation starts.
endTriggered when the animation ends.
pauseTriggered when the animation is paused.
resumeTriggered when the animation is resumed.
destroyTriggered when the instance is destroyed.
wordTransitionStartTriggered at the start of a word transition.
wordTransitionEndTriggered at the end of a word transition.
scrambleStartTriggered when the letters scrambler starts.
scrambleEndTriggered when the letters scrambler ends.
letterScrambleStartTriggered when a letter scrambling starts.
letterScramblingTriggered when a letter scrambles.
letterScrambleEndTriggered 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:

NameEffect
fadeInWords fade in
slideInTopWords slide+fade in from top to bottom
slideInBottomWords slide+fade in from bottom to top
slideInLeftWords slide+fade in from left to right
slideInRightWords slide+fade in from right to left
revealInTopWords slide+fade in from top to bottom inside a hidden container
revealInBottomWords 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']
  }
})
OptionsTypeDefaultDescription
classnamestringhighlightClass name to append to the highlighted word tags
tagstringstrongHTML tag to wrap the highlighted word
wordsarray[]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!

1.6.4

6 months ago

1.6.3

7 months ago

1.6.2

7 months ago

1.6.1

7 months ago

1.6.0

7 months ago

1.5.0

2 years ago

1.4.0

2 years ago

1.3.4

2 years ago

1.3.3

2 years ago

1.3.2

2 years ago

1.2.0

2 years ago

1.1.0

3 years ago

1.0.9

3 years ago

1.0.8

3 years ago

1.0.7

3 years ago

1.0.6

4 years ago

1.0.4

4 years ago

1.0.3

4 years ago

1.0.2

4 years ago

1.0.1

4 years ago

1.0.0

4 years ago