JavaScript API

init()

init(options?)

Initialises observers for every element possessing data-mos. Call this once on page load after registering any additional presets desired.

import { MOS } from 'motion-on-scroll';

MOS.init({
  offset: 200,
  duration: 600,
  easing: 'ease-out',
  once: true
});

Options

offset

Type: number (pixels)
Default: 120

Additional distance (in pixels) before an element is considered in view.

duration

Type: number
Default: 400

Animation duration. (MOS uses the browser’s Web Animations API where possible.)

delay

Type: number
Default: 0

Delay before the animation starts.

timeUnits

Type: "ms" | "s"
Default: "ms"

Units for duration and delay.

distance

Type: number (pixels)
Default: 24

Travel distance for directional presets like fade-up.

easing

Type: string
Default: 'ease'

Supports any of these predefined keywords:

• linear, ease
• ease-in, ease-out, ease-in-out
• circ-in, circ-out, circ-in-out
• back-in, back-out, back-in-out, anticipate
• ease-in-back, ease-out-back, ease-in-out-back
• ease-in-sine, ease-out-sine, ease-in-out-sine
• ease-in-quad, ease-out-quad, ease-in-out-quad
• ease-in-cubic, ease-out-cubic, ease-in-out-cubic
• ease-in-quart, ease-out-quart, ease-in-out-quart

You can also pass a custom cubic-bezier string in any of the following formats:

• cubic-bezier(x1, y1, x2, y2)
• [x1,y1,x2,y2] or x1,y1,x2,y2

Need something else? Define a custom easing preset with MOS.registerEasing and use it in your presets.

once

Type: boolean
Default: false

Play only once, then unobserve the element.

mirror

Type: boolean
Default: false

If true, elements animate when scrolling up as well as down (requires once: false).

disable

Type: boolean | 'mobile' | 'phone' | 'tablet' | (() => boolean)
Default: false

Disable animations entirely under specific conditions (e.g. on mobile).

disableMutationObserver

Type: boolean
Default: false

Skip the automatic MutationObserver (useful when you manage DOM changes manually).

startEvent

Type: string
Default: "DOMContentLoaded"

DOM event that triggers MOS to start. Defaults to “DOMContentLoaded”.

throttleDelay

Type: number
Default: 99

Throttle delay for scroll events in ms.

debounceDelay

Type: number
Default: 50

Debounce delay for resize/orientation events in ms.

refresh()

Update all element positions and re-initialize the scroll system.

refreshHard()

Re-evaluates the DOM for all [data-mos] elements and calls refresh(). Useful after client-side navigation or significant DOM changes. This is internally called automatically when DOM changes are detected, unless you disable the mutation observer.

Register Custom Presets

Functions are exposed to allow you to register custom keyframes, easings, or even whole animations for complex use cases.

Caution

You should register any custom presets before calling MOS.init().

registerKeyframes()

registerKeyframes(name, definition)

Registers custom keyframes that can subsequently be referenced via the data-mos attribute.

import { MOS } from 'motion-on-scroll';

MOS.registerKeyframes("my-custom-animation", {
  opacity: [0, 1],
  rotate: [0, 360],
});

// initialize MOS after registering keyframes
MOS.init();

<!-- somewhere in html -->
<div data-mos="my-custom-animation"></div>

name

Type: string
Unique identifier (case-sensitive). Must be non-empty and cannot collide with existing easing keywords.

definition

Type: DOMKeyframesDefinition
Any keyframes object accepted by motion’s animate function.

registerEasing()

registerEasing(name, definition)

Registers a custom easing that can subsequently be referenced via the easing option of MOS.init() or within any data-mos-easing attribute.

import { MOS } from 'motion-on-scroll';

// Register a cubic-bezier array
MOS.registerEasing('bouncy', [0.68, -0.55, 0.265, 1.55]);

// Register a cubic-bezier string (will be parsed)
MOS.registerEasing('custom', 'cubic-bezier(0.25, 0.46, 0.45, 0.94)');

// initialize MOS after registering easings
MOS.init({
  easing: 'bouncy',
});

<!-- or somewhere in html -->
<div data-mos="fade-up" data-mos-easing="bouncy"></div>

name

Type: string
Unique identifier (case-sensitive). Must be non-empty and cannot collide with existing easing keywords.

definition

Type: EasingDefinition | string
Any easing accepted by Motion — named keyword, cubic-bezier array, or cubic-bezier string.

The function validates the input and throws if the easing cannot be parsed.

registerAnimation()

registerAnimation(name, factory)

Registers a custom animation that can subsequently be referenced via the data-mos attribute. This enables you to completely customize the animation logic using motion’s animate function.

import { MOS } from 'motion-on-scroll';
import { animate } from "motion";

registerAnimation("bouncy", (el, opts) =>
  animate(
    el,
    { opacity: [0, 1], scale: [0.4, 1] },
    {
      type: "spring",
      bounce: 0.5,
      duration: opts.timeUnits === "s" ? opts.duration : opts.duration / 1000,
      delay: opts.timeUnits === "s" ? opts.delay : opts.delay / 1000,
    },
  ),
);

// initialize MOS after registering animation
MOS.init();

<!-- somewhere in html -->
<div data-mos="bouncy"></div>

Note

If you happen to name a custom animation the same as existing keyframes, the custom animation will take precedence.

name

Type: string
Unique identifier (case-sensitive). Must be non-empty.

factory

Type: (el: HTMLElement, opts: ElementOptions) => AnimationPlaybackControls
A factory function that uses motion’s animate function to create an animation.

ElementOptions is an object that contains the merged global options and element-level options. It has the following properties which you can use to enable customizable animations via data attributes on individual elements:

interface ElementOptions {
  /** Additional px distance before an element is considered in view */
  offset: number;
  /** Animation duration default */
  duration: number;
  /** Delay before starting the animation */
  delay: number;
  /** Units for duration and delay ("ms" or "s") */
  timeUnits: "ms" | "s";
  /** Travel distance for directional animations in px */
  distance: number;
  /** CSS easing string */
  easing: EasingKeyword | string;
  /** If true, an element animates only once */
  once: boolean;
  /** If true, elements animate when scrolling up as well as down (requires once: false) */
  mirror: boolean;
  /** Disable condition */
  disable: DeviceDisable;
  /** If true, automatic DOM MutationObserver is not started */
  disableMutationObserver: boolean;
  /** DOM event that triggers MOS to start. Defaults to "DOMContentLoaded" */
  startEvent: string;
  /** Throttle delay for scroll events in ms */
  throttleDelay: number;
  /** Debounce delay for resize/orientation events in ms */
  debounceDelay: number;
}

Named exports

motion-on-scroll also exports functions directly:

import { init, refresh, refreshHard, registerAnimation, registerEasing, registerKeyframes } from 'motion-on-scroll';

They are identical to the namespaced versions.