murphyjs - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #rust #linux #java #windows #cli #kubernetes #awesome-list #pytorch #open-source

murphyjs

(★ 112)

A JavaScript vanilla library to scroll based reveal animations. The murphy.js is a lightweight JavaScript animation library with a simple implementation way. All this works by joining of data-attributes, Web animate API and Intersection Observer API.

File Explorer

Download Latest Version (.zip)

- DemoContainer.tsx
- DemoControls.tsx
- index.js
- _app.tsx
- _meta.json
- api-reference.mdx
- examples.mdx
- getting-started.mdx
- index.mdx
- - config.js
  - index.js
- .DS_Store
- favicon.ico
- globals.css
- murphy.d.ts
.DS_Store
.gitignore
.npmignore
babel.librc
LICENSE
logo.png
murphyjs-2.4.4.tgz
murphyjs-2.5.0.tgz
murphyjs-2.5.1.tgz
next-env.d.ts
next.config.js
package-lock.json
package.json
postcss.config.js
README.md
tailwind.config.js
theme.config.tsx
tsconfig.json
vercel.json
webpack.config.js
yarn.lock

# Installation Guide

1. Get the code

git clone https://github.com/cesarolvr/murphyjs

Downloads the entire project code from GitHub to your computer.

cd murphyjs

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install murphyjs

Downloads and installs the libraries listed in package.json.

yarn add murphyjs

Type this command into your terminal and run it.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MurphyJS

<div align="center">
  
  <img src="logo.png" alt="MurphyJS Logo" width="600"/>
  <br/><br/>
  <img src="https://img.shields.io/npm/v/murphyjs.svg" alt="npm version" />
  
  <img src="https://img.shields.io/npm/dm/murphyjs" alt="npm downloads" />
  <img src="https://img.shields.io/github/license/cesarolvr/murphyjs" alt="license" />
  <br />
  <br />

A lightweight JavaScript library for creating smooth animations with a simple API.
</div>

## Features

- 🚀 Lightweight and fast (only 3.7KB)
- 🎨 Simple and intuitive API
- 🌈 Beautiful animations
- 📱 Mobile-friendly
- 🎯 No dependencies
- 🎮 Total control of IntersectionObserver parameters
- 🎁 Some animations implemented by default
- 🏝 Plug and play solution to landing pages and simple projects
- ❎ Native fallback to not supported browsers
- 🛎️ Built-in event system for animation lifecycle (in, out, finish, cancel, reset, cleanup)
- 🔄 Mirror animations for smooth scroll transitions
- 📏 Viewport position control with predefined aliases
- 📱 Mobile optimization with device detection

## Installation

Using npm:
```bash
npm install murphyjs
```

Using yarn:
```bash
yarn add murphyjs
```

Using CDN:
```html
<script src="https://unpkg.com/murphyjs@2.5.1/dist/index.js"></script>
<script>
  // Call play() after the script is loaded
  if (typeof window !== "undefined" && window.murphy) {
    window.murphy.play();
  }
</script>
```

For detailed documentation and examples, visit our [documentation site](https://www.murphyjs.org/).

## Quick Start

```javascript
import { Murphy } from 'murphyjs';

// Create a new instance
const murphy = new Murphy();

// Animate elements
murphy.animate('.box', {
  opacity: [0, 1],
  y: [20, 0],
  duration: 1000
});
```

## Usage

### 1. Tag your HTML

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

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

The default effect of murphy is `bottom-to-top`, but you can also use:
- `top-to-bottom`
- `left-to-right`
- `right-to-left`

### 2. Reset your CSS

In your CSS, reset all the tagged elements:

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

### 3. Start murphy

In JavaScript, import and run `play` when your page is completely loaded:

```javascript
import murphy from "murphyjs";
murphy.play();
```

Or if you're using the script tag:

```html
<script src="./murphy/index.js"></script>
<script>
  murphy.play();
</script>
```

## Configuration

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

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| data-murphy | String | 'bottom-to-top' | Animation direction |
| data-murphy-appearance-distance | Int | 50px | Distance from viewport edge to trigger animation |
| data-murphy-element-distance | Int | 30px | Distance the element moves during animation |
| data-murphy-ease | String | 'ease' | Animation easing function (can be a cubic-bezier) |
| data-murphy-animation-delay | Int | 300ms | 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 | 300ms | 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-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 <= 768px or mobile user agent) |

## Advanced Features

### Mirror Animations

Enable mirror animations to create smooth transitions when elements leave the viewport:

```html
<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 Control

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:

```html

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

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

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

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

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

### 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'` |

## Group-based Animations

You can group elements using the `data-murphy-group` attribute. This allows you to control animations for specific groups of elements. For example, you can play or reset animations for only a subset of elements by specifying a group name:

```html
<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>
```

You can then control animations for a specific group using the API:

```js
// Play animations for group1 only
murphy.play('group1');

// Reset animations for group2 only
murphy.reset('group2');
```

## API

### Global Methods

| Method | Description |
|--------|-------------|
| `play(group?: string)` | Start monitoring elements in DOM tagged with `data-murphy` attribute. Optionally specify a group to animate only elements in that group. |
| `cancel()` | Cancel all animations and reset elements to their final state. |
| `reset(group?: string)` | Reset all animations to their initial state. Optionally specify a group to reset only elements in that group. |
| `cleanup()` | Disconnect all Intersection Observers and clean up resources. |

### Murphy Class

The `Murphy` class provides a programmatic way to create animations:

```javascript
import { Murphy } from 'murphyjs';

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

### Events

MurphyJS 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

```javascript
document.addEventListener('murphy:in', (event) => {
  const { element } = event.detail;
  console.log('Element entered viewport:', element);
});

document.addEventListener('murphy:finish', (event) => {
  const { element } = event.detail;
  console.log('Animation finished:', element);
});
```

### Available Animations

MurphyJS comes with several built-in animations that you can use with the `data-murphy` attribute:

#### Basic Animations
- `bottom-to-top`
- `top-to-bottom`
- `left-to-right`
- `right-to-left`

#### Flip Animations
- `flip-left`
- `flip-right`
- `flip-up`
- `flip-down`

#### Zoom Animations
- `zoom-in`
- `zoom-out`

#### Fade Animations
- `fade`
- `fade-up`
- `fade-down`
- `fade-left`
- `fade-right`

#### Rotate Animations
- `rotate-left`
- `rotate-right`

#### Scale Animations
- `scale-up`
- `scale-down`

#### Slide Animations
- `slide-up`
- `slide-down`
- `slide-left`
- `slide-right`

#### Bounce Animations
- `bounce-in`
- `bounce-out`