Under the hood 🛠️
A complete reference of murphy.js's API, including attributes, methods, and configuration options.
Data Attributes
murphy.js uses data attributes to configure animations. Here's a complete list of available attributes:
| Attribute | Type | Default | Description |
|---|---|---|---|
data-murphy | String | 'bottom-to-top' | Animation direction. Available values: 'bottom-to-top', 'top-to-bottom', 'left-to-right', 'right-to-left' |
data-murphy-appearance-distance | Number | 50 | Distance in pixels from viewport edge to trigger animation |
data-murphy-element-distance | Number | 30 | Distance in pixels the element moves during animation |
data-murphy-ease | String | 'ease' | Animation easing function. Can be any valid CSS easing function or cubic-bezier |
data-murphy-animation-delay | Number | 300 | Delay in milliseconds before animation starts |
data-murphy-element-threshold | Number | 1.0 | How much of the element needs to be visible to trigger (0-1, where 1 means 100% visible) |
data-murphy-animation-duration | Number | 300 | Duration of the animation in milliseconds |
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-group | String | undefined | Group identifier for controlling animations for specific groups of elements |
data-murphy-mirror | Boolean | false | Whether to play the animation in reverse when the element leaves the viewport |
data-murphy-disable-mobile | Boolean | false | Whether to disable animations on mobile devices (screen width < 769px or mobile user agent) |
Methods
play()
Starts monitoring elements in DOM tagged with data-murphy attribute.
import murphy from 'murphyjs';
// Start monitoring
murphy.play();reset()
Resets all data-murphy elements to their initial state.
// Reset all animations
murphy.reset();cleanup()
Disconnects all Intersection Observers and cleans up resources.
// Clean up resources
murphy.cleanup();Murphy Class
The Murphy class provides a programmatic way to create animations:
// Create a new instance
const murphy = new Murphy();
// Animate elements
murphy.animate('.box', {
opacity: [0, 1],
y: [20, 0],
duration: 1000
});animate(selector, options)
Animates elements matching the selector with the specified options.
Parameters
| Parameter | Type | Description |
|---|---|---|
selector | String | CSS selector for target elements |
options | Object | Animation configuration |
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 |
Example
const murphy = new Murphy();
// Fade in and slide up
murphy.animate('.fade-in', {
opacity: [0, 1],
y: [20, 0],
duration: 1000
});
// Slide in from left
murphy.animate('.slide-in', {
x: [-100, 0],
duration: 800,
ease: 'ease-out'
});
// Complex animation
murphy.animate('.complex', {
opacity: [0, 1],
x: [-50, 0],
y: [30, 0],
duration: 1200,
delay: 200,
ease: 'cubic-bezier(0.4, 0, 0.2, 1)'
});Events
murphy.js provides a set of events that you can listen to for better control and integration:
| 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 |
Event Example
// Listen for elements entering the viewport
document.addEventListener('murphy:in', ({ detail }) => {
console.log('Element entered viewport:', detail.element);
console.log('Intersection ratio:', detail.intersectionRatio);
});
// Listen for animation completion
document.addEventListener('murphy:finish', ({ detail }) => {
console.log('Animation finished:', detail.element);
});
// Listen for elements leaving the viewport
document.addEventListener('murphy:out', ({ detail }) => {
console.log('Element left viewport:', detail.element);
console.log('Intersection ratio:', detail.intersectionRatio);
});Practical Example
Here's a practical example of using events to add custom behavior:
// Add a class when element enters viewport
document.addEventListener('murphy:in', ({ detail }) => {
detail.element.classList.add('is-visible');
});
// Remove class when element leaves viewport
document.addEventListener('murphy:out', ({ detail }) => {
detail.element.classList.remove('is-visible');
});
// Log animation progress
document.addEventListener('murphy:finish', ({ detail }) => {
console.log(`Animation completed for ${detail.element.id || 'unnamed element'}`);
});
// Track animation errors
document.addEventListener('murphy:in', ({ detail }) => {
if (detail.error) {
console.warn('Animation error:', detail.error);
}
});Usage Examples
Basic Animation
<div data-murphy="bottom-to-top">
This element will animate from bottom to top
</div>Mirror Animation
<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>Viewport Position Examples
You can control when animations trigger based on the element's position in the viewport using data-murphy-root-margin:
<!-- Using aliases -->
<div data-murphy="bottom-to-top" data-murphy-root-margin="middle">
Animates at middle of viewport
</div>
<div data-murphy="bottom-to-top" data-murphy-root-margin="bottom">
Animates at bottom of viewport
</div>
<div data-murphy="bottom-to-top" data-murphy-root-margin="quarter">
Animates at 25% from bottom
</div>
<div data-murphy="bottom-to-top" data-murphy-root-margin="three-quarters">
Animates at 75% from bottom
</div>
<!-- Using raw values -->
<div data-murphy="bottom-to-top" data-murphy-root-margin="0px 0px -50% 0px">
Animates at middle of viewport
</div>
<div data-murphy="bottom-to-top" data-murphy-root-margin="0px 0px 0px 0px">
Animates at bottom of viewport
</div>
<div data-murphy="bottom-to-top" data-murphy-root-margin="0px 0px -25% 0px">
Animates at 25% from bottom
</div>
<div data-murphy="bottom-to-top" data-murphy-root-margin="0px 0px -75% 0px">
Animates at 75% from bottom
</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.
Available Viewport Position Aliases
| Alias | Description | Raw Value |
|---|---|---|
top | Triggers at top of viewport | '0px 0px 0px 0px' |
middle | Triggers at middle of viewport | '0px 0px -50% 0px' |
bottom | Triggers at bottom of viewport | '0px 0px 0px 0px' |
quarter | Triggers at 25% from bottom | '0px 0px -25% 0px' |
three-quarters | Triggers at 75% from bottom | '0px 0px -75% 0px' |