Let's roll 🎯

Installation

Via npm

npm install murphyjs

Via yarn

yarn add murphyjs

Via file include

Download file here (opens in a new tab) and link in your HTML:

<script src="./murphy/index.js"></script>

Basic Setup

1. Tag your HTML

In your markup, decorate your element with attribute data-murphy:

<div data-murphy="left-to-right">Any content here</div>

The default effect of murphy.js is bottom-to-top, but it's possible to use:

top-to-bottom
left-to-right
right-to-left

2. Reset your CSS

In your CSS, reset all the tagged elements:

*[data-murphy] {
  opacity: 0;
}

3. Start murphy.js

Import

import murphy from "murphyjs";

And trigger

murphy.play()

Or call from window

If you added murphy.js via file include, just access murphy.js's functions in window:

window.murphy.play()
// or just
murphy.play()

Class-based Usage

You can also use MurphyJS with a class-based approach for more programmatic control:

// Create a new instance
const murphy = new Murphy();
 
// Animate elements
murphy.animate('.box', {
  opacity: [0, 1],
  y: [20, 0],
  duration: 1000
});

The animate method accepts the following options:

Option	Type	Default	Description
opacity	Array	[0, 1]	Start and end opacity values
x	Array	[0, 0]	Start and end x translation in pixels
y	Array	[0, 0]	Start and end y translation in pixels
duration	Number	1000	Animation duration in milliseconds
delay	Number	0	Delay before animation starts in milliseconds
ease	String	'ease'	Easing function name

Available Animations

Basic Animations

<p data-murphy="bottom-to-top">Bottom to top</p>
<p data-murphy="top-to-bottom">Top to bottom</p>
<p data-murphy="left-to-right">Left to right</p>
<p data-murphy="right-to-left">Right to left</p>

Sequential Animations

To create sequential animations like murphy.js's logo:

<p data-murphy="bottom-to-top">m</p>
<p data-murphy="bottom-to-top" data-murphy-animation-delay="400">u</p>
<p data-murphy="bottom-to-top" data-murphy-animation-delay="500">r</p>
<p data-murphy="bottom-to-top" data-murphy-animation-delay="600">p</p>
<p data-murphy="bottom-to-top" data-murphy-animation-delay="700">h</p>
<p data-murphy="bottom-to-top" data-murphy-animation-delay="800">y</p>
<p data-murphy="bottom-to-top" data-murphy-animation-delay="900">.</p>
<p data-murphy="bottom-to-top" data-murphy-animation-delay="1000">j</p>
<p data-murphy="bottom-to-top" data-murphy-animation-delay="1100">s</p>

Group-based Animations

You can group elements using the data-murphy-group attribute. This allows you to control animations for specific groups of elements.

<div data-murphy="bottom-to-top" data-murphy-group="group1">Group 1</div>
<div data-murphy="top-to-bottom" data-murphy-group="group1">Group 1</div>
<div data-murphy="left-to-right" data-murphy-group="group2">Group 2</div>
<div data-murphy="right-to-left" data-murphy-group="group2">Group 2</div>

Configuration Options

You can configure the animation of each decorated element individually using these attributes:

Attribute	Value type	Default value	What controls
data-murphy	String	'bottom-to-top'	Animation direction
data-murphy-appearance-distance	Int	50 (px)	Distance from viewport edge to trigger animation
data-murphy-element-distance	Int	30 (px)	Distance the element moves during animation
data-murphy-ease	String	'ease'	Define a função de easing da animação. Opções: 'ease', 'ease-in', 'ease-out', 'ease-in-out', 'cubic-in', 'cubic-out', 'cubic-in-out', 'quad-in', 'quad-out', 'quad-in-out'
data-murphy-animation-delay	Int	300 (ms)	Delay before animation starts
data-murphy-element-threshold	Float	1.0	How much of the element needs to be visible to trigger (0-1)
data-murphy-animation-duration	Int	300 (ms)	Duration of the animation
data-murphy-root-margin	String	'0px 0px -50px 0px'	Custom root margin for the Intersection Observer. Use this to control when animations trigger based on viewport position. You can use predefined aliases: 'top', 'middle', 'bottom', 'quarter', 'three-quarters'
data-murphy-mirror	Boolean	false	Whether to play the animation in reverse when the element leaves the viewport

Viewport Position Control

You can control when animations trigger based on the element's position in the viewport using the data-murphy-root-margin attribute. For convenience, we provide several aliases:

<!-- Animate when element reaches middle of viewport -->
<div data-murphy="bottom-to-top" data-murphy-root-margin="middle">
  This will animate when it reaches the middle of the viewport
</div>
 
<!-- Animate when element reaches bottom of viewport -->
<div data-murphy="bottom-to-top" data-murphy-root-margin="bottom">
  This will animate when it reaches the bottom of the viewport
</div>
 
<!-- Animate when element is 25% from bottom of viewport -->
<div data-murphy="bottom-to-top" data-murphy-root-margin="quarter">
  This will animate when it's 25% from the bottom of the viewport
</div>
 
<!-- Animate when element is 75% from bottom of viewport -->
<div data-murphy="bottom-to-top" data-murphy-root-margin="three-quarters">
  This will animate when it's 75% from the bottom of the viewport
</div>

You can also use raw CSS margin values if you need more precise control:

<div data-murphy="bottom-to-top" data-murphy-root-margin="0px 0px -50% 0px">
  This will animate when it reaches the middle of the viewport
</div>

The root margin follows the CSS margin syntax: top right bottom left. Negative values create an inset margin, which means the animation will trigger when the element reaches that point in the viewport.

Methods

Method	What happens
play	Start monitoring elements in DOM tagged with `data-murphy`
reset	Resets all data-murphy elements to their initial state
cleanup	Disconnects all Intersection Observers and cleans up resources

Advanced: Mirror Animations

You can enable mirror animations to create smooth transitions when elements leave the viewport:

<div data-murphy="bottom-to-top" data-murphy-mirror="true">
  This element will animate in when scrolling down and animate out when scrolling up
</div>

Browser Support

Chrome	Safari	IE / Edge	Firefox	Opera
58+	12.1+	Not (yet) supported	55+	62+

Important Note

👋 Just a quick tip: While these animations are triggered by scrolling, they also work great for elements that are already visible on the page. Think of it like having those cool entrance animations from React Transition Group, but without the extra setup! Perfect for spicing up your landing pages and first-time visits. Give it a try! ✨

Advanced: Listening to Animation Events

murphy.js emits custom events for each animation lifecycle. You can listen to these events for advanced integrations:

Event	Description
murphy:in	Fired when an element enters the viewport
murphy:out	Fired when an element leaves the viewport
murphy:finish	Fired when an animation completes
murphy:cancel	Fired when an animation is cancelled
murphy:reset	Fired when an element is reset
murphy:cleanup	Fired when observers are cleaned up

Example:

document.addEventListener('murphy:in', ({ detail }) => {
  console.log('Element entered viewport:', detail.element);
});
document.addEventListener('murphy:finish', ({ detail }) => {
  console.log('Animation finished:', detail.element);
});

API Reference