repository·master·Indexed 25 days ago
https://github.com/nolimits4web/atroposA lightweight, open-source JavaScript library for creating touch-friendly 3D parallax hover effects. Atropos supports vanilla JS, React, and Web Components, providing a configurable system to apply rotation, scaling, and depth offsets to elements via the AtroposOptions API and data attributes.
To build a development version of Atropos, first install all dependencies from the repository root, then run the development build command. The output will be available in the build/ folder.
$ npm install
$ npm run build:devTo generate the production-ready version of Atropos, run the production build command. The resulting stable JS and CSS files will be located in the package/ folder. Do not use files from the build/ folder for production environments.
$ npm run build:prodDemos for the different versions of Atropos are located in the ./playground folder. You can run them using the following commands:
npm run corenpm run reactFor detailed implementation guides, API references, and examples, visit the official Atropos resources:
You can create depth within an Atropos container by applying offsets to child elements using data-* attributes. Atropos will automatically calculate their movement based on the parent's rotation.
Supported Attributes:
data-atropos-offset: A number representing the percentage offset. A value of 10 means the child moves 10% of the rotation intensity.data-atropos-opacity: A semicolon-separated list of two numbers (e.g., 0;1) representing the minimum and maximum opacity during rotation.Example HTML Structure:
<div class="atropos-container">
<div class="atropos-rotate">
<div class="atropos-scale">
<div class="atropos-inner">
<!-- This child will move with a 20% offset -->
<div data-atropos-offset="20">Child Content</div>
<!-- This child will fade from 0 to 1 opacity -->
<div data-atropos-opacity="0;1">Fading Child</div>
</div>
</div>
</div>
</div>The params object passed to the Atropos constructor accepts the following configuration keys:
| Key | Type | Default | Description |
|---|---|---|---|
alwaysActive | boolean | false | If true, the effect is always applied without needing pointer interaction. |
activeOffset | number | 50 | The Z-axis offset applied to the scale element when active. |
shadowOffset | number | 50 | The Z-axis offset for the shadow element. |
shadowScale | number | 1 | The scale applied to the shadow element. |
duration | number | 300 | Transition duration in milliseconds. |
rotate | boolean | true | Whether to enable rotation. |
rotateTouch | boolean | true | Whether to enable rotation on touch devices. Can be 'scroll-y' or 'scroll-x' to handle scrolling conflicts. |
rotateXMax | number | 15 | Maximum rotation angle on the X axis. |
rotateYMax | number | 15 | Maximum rotation angle on the Y axis. |
rotateXInvert | boolean | false | If true, inverts the X rotation direction. |
rotateYInvert | boolean | false | If true, inverts the Y rotation direction. |
stretchX | number | 0 | Percentage of X-axis stretching based on rotation. |
stretchY | number | 0 | Percentage of Y-axis stretching based on rotation. |
stretchZ | number | 0 | Z-axis stretching based on rotation. |
commonOrigin | boolean | true | If true, uses a common transform origin for rotation. |
shadow | boolean | true | Whether to enable the shadow effect. |
highlight | boolean | true | Whether to enable the highlight effect. |
onEnter | function | null | Callback triggered when the element is activated. |
onLeave | function | null | Callback triggered when the element is deactivated. |
onRotate | function | null | Callback triggered on every rotation update. Receives (rotateX, rotateY). |
When initializing Atropos, you can pass an AtroposOptions object to customize the behavior of the effect.
Key configuration properties include:
el: The target HTMLElement or CSSSelector to apply the effect to.eventsEl: The HTMLElement or CSSSelector that triggers the effect (e.g., a container for mouse/touch events).alwaysActive: If true, the effect is always active.activeOffset: Offset for the active state.shadowOffset, shadowScale: Controls for the shadow effect.duration: Animation duration.rotate, rotateTouch: Enables rotation on mouse or touch. rotateTouch can be set to 'scroll-x' or 'scroll-y'.rotateXMax, rotateYMax: Maximum rotation angles.rotateXInvert, rotateYInvert: Whether to invert the rotation direction.stretchX, stretchY, stretchZ: Controls for the stretching effect.commonOrigin: Whether to use a common origin for the effect.shadow: Enables/disables the shadow effect.highlight: Enables/disables the highlight effect.onEnter: Callback function triggered when the element becomes active.onLeave: Callback function triggered when the element becomes inactive.onRotate: Callback function triggered during rotation, receiving x and y coordinates: (x: number, y: number) => void.Atropos function with an AtroposOptions object. This returns an AtroposInstance which allows you to interact with or destroy the effect.The AtroposInstance object returned by the constructor provides access to the current state of the effect and a method to clean it up.
Properties:
el: The HTMLElement being controlled.isActive: Boolean indicating if the effect is currently active.destroyed: Boolean indicating if the instance has been destroyed.params: The original AtroposOptions used for initialization.Methods:
destroy(): Removes the effect and cleans up event listeners.The <atropos-component> element dispatches several custom events that you can listen to for interaction tracking:
enter: Dispatched when the user enters the element.leave: Dispatched when the user leaves the element.rotate: Dispatched during rotation. The rotation data is available in the event.detail property.To create a 3D parallax effect, instantiate the Atropos constructor by passing an object containing the target element and configuration parameters. The constructor returns an object that allows you to manually destroy the instance.
Parameters:
el: The target DOM element (or a CSS selector string) to apply the effect to.eventsEl: (Optional) The element that listens for pointer events. Defaults to el if not provided.isComponent: (Optional) Boolean. If true, childrenRootEl is set to the host of the parent node (useful for Web Components).params: Configuration object (see Atropos configuration options).