simpleParallax.js Documentation

Install the package using your preferred package manager.

Note for React users: react and react-dom (>= 17) are peer dependencies. The package includes built-in TypeScript definitions for both React and Vanilla entry points.

npm install simple-parallax-js
yarn add simple-parallax-js
pnpm add simple-parallax-js
bun add simple-parallax-js

The ParallaxOptions interface defines the configuration settings for a parallax effect. Use these properties to control the movement direction, speed, and visual behavior of the parallax elements.

Available options:

• delay: A number representing the delay before the effect starts.
• maxTransition: A number defining the maximum transition distance.
• orientation: An Orientation value determining the direction of movement.
• overflow: A boolean indicating whether to handle overflow behavior.
• scale: A number controlling the scaling factor.
• transition: A string defining the CSS transition timing function.

export interface ParallaxOptions {
  delay: number;
  maxTransition: number;
  orientation: Orientation;
  overflow: boolean;
  scale: number;
  transition: string;
}

When instantiating SimpleParallax, you can provide an optional options object to customize the behavior of the parallax instances. These options are merged with the library's DEFAULTS.

Common configuration keys include:

• customContainer: An element that acts as the viewport/container for the parallax calculations. If provided, visibility is checked relative to this container.
• overflow: A boolean that determines if the element should be wrapped in a container. If set to false, the library will unwrap the element when destroy() is called.
• scale: A number determining the scaling factor of the parallax effect.
• orientation: A string determining the direction of the effect.

Note: The settings object is applied to all elements passed to the constructor.

When initializing a parallax effect without providing specific settings, the library uses the following default values. These options control the timing, direction, scaling, and CSS transition behavior of the parallax movement.

{
  delay: 0.4,
  orientation: "up",
  scale: 1.5,
  overflow: false,
  transition: "cubic-bezier(0,0,0,1)",
  maxTransition: 0
}

When using simple-parallax-js in a React environment, the SimpleParallaxProps interface defines the configuration options available for the parallax component. These props control the movement behavior, transition timing, and visual constraints of the parallax effect.

export interface SimpleParallaxProps {
  children?: React.ReactNode;
  delay?: number;
  maxTransition?: number | null;
  orientation?: Orientation;
  overflow?: boolean;
  scale?: number;
  transition?: string;
}

To create parallax effects on elements using vanilla JavaScript, instantiate the SimpleParallax class. You can pass a single element, a string (selector), a NodeList, an HTMLCollection, or an array of Element objects.

By default, the library respects the user's system preference for reduced motion. If prefers-reduced-motion is enabled, the parallax effects will not be initialized. The library also listens for changes to this preference dynamically: if a user enables reduced motion, the effects are destroyed; if they disable it, the effects are reinitialized.

Supported elements are automatically converted to an array internally.

To clean up parallax effects, remove event listeners (like resize), stop animation frames, and reset element styles, call the .destroy() method on your SimpleParallax instance.

If you configured overflow: false in your settings, calling destroy() will also unwrap the elements from their parallax wrapper containers. If no more active instances exist in the library's internal registry, the global animation loop and resize listeners are fully detached.

The Orientation type specifies the direction in which the parallax effect moves. You can choose from cardinal directions, diagonal directions, or single axes.

Supported values:

• "up"
• "right"
• "down"
• "left"
• "up left"
• "up right"
• "down left"
• "down right"

export type Orientation =
  | "up"
  | "right"
  | "down"
  | "left"
  | "up left"
  | "up right"
  | "down left"
  | "down right";