🔥 Meet Our New Project: t0ggles - Your Ultimate Project Management Tool! 🔥
JavaScriptReactVueSvelteElement

Documentation

Browser Compatibility

Atropos is compatible with browsers which support the following features:

Installation

We can install Atropos from NPM

npm i atropos

Styles

First we need to include Atropos stylesheet:

<link rel="stylesheet" href="path/to/atropos.css" />

With bundler (like webpack) you can import styles directly from JavaScript:

// main.js
import 'atropos/css'

If you use SCSS preprocessor you can import Atropos's styles from SCSS in the following way:

// main.scss
@import 'atropos/scss'

Atropos comes with stylesheets in different formats. The following files are available:

  • atropos.css (exported as atropos/css) - all Atropos styles
  • atropos.min.css (exported as atropos/css/min) - minified Atropos styles
  • atropos.scss (exported as atropos/scss) - Atropos styles in SCSS syntax
  • atropos.less (exported as atropos/less) - Atropos styles in LESS syntax

HTML Layout

Now, we need to add basic Atropos layout to our app:

<!-- main Atropos container (required), add your custom class here -->
<div class="atropos my-atropos">
<!-- scale container (required) -->
<div class="atropos-scale">
<!-- rotate container (required) -->
<div class="atropos-rotate">
<!-- inner container (required) -->
<div class="atropos-inner">
<!-- put your custom content here -->
</div>
</div>
</div>
</div>

Initialize Atropos

Now we need to initialize Atropos:

// import Atropos library
import Atropos from 'atropos';
// Initialize
const myAtropos = Atropos({
el: '.my-atropos',
// rest of parameters
});

If you use it in environment without ES modules, you can add Atropos library via <script> tag:

<script src="path/to/atropos.min.js"></script>
<script>
const myAtropos = Atropos({
el: '.my-atropos',
// rest of parameters
});
</script>

If you use modules directly in browser, then it can be imported from CDN:

import Atropos from 'https://cdn.jsdelivr.net/npm/atropos@2/atropos.min.mjs';
const myAtropos = Atropos({
el: '.my-atropos',
// rest of parameters
});

In addition to Atropos's main CSS styles, we may need to add some custom styles, for example to set Atropos size:

.my-atropos {
width: 320px;
height: 160px;
}

Parameters

NameTypeDefaultDescription
elHTMLElement | string Atropos element
eventsElHTMLElement | stringPointer events target. If not specified event handlers will be attached to main container (el)
activeOffsetnumber50Main container offset when activated (on hover), basically means translateZ value
alwaysActivebooleanfalseEnables Atropos to be always active
durationnumber300Transition duration when activated, leave and and during rotate (in ms)
rotatebooleantrueDefines whether to rotate container on pointer move (when activated)
rotateTouchboolean | stringtrueDefines whether to rotate container on touch move (when activated), rotate must be enabled. Also accepts special values:
  • scroll-y - will not rotate container with initial vertical touch-move (vertical scrolling), basically will not block page vertical scrolling
  • scroll-x - will not rotate container with initial horizontal touch-move (horizontal scrolling), basically will not block page horizontal scrolling
rotateXMaxnumber15Max rotation along the X-axis (in deg)
rotateYMaxnumber15Max rotation along the Y-axis (in deg)
rotateXInvertbooleanfalseInverts rotation along the X-axis (in deg)
rotateYInvertbooleanfalseInverts rotation along the Y-axis (in deg)
stretchXnumber0Move (translate) atropos container along the X-axis on this value (in percentage). E.g. `50` value will move container +-50% of its width. Only for multiple Atropos, when multiple Atropos uses same parent `eventsEl` container
stretchYnumber0Move (translate) atropos container along the Y-axis on this value (in percentage). E.g. `50` value will move container +-50% of its height. Only for multiple Atropos, when multiple Atropos uses same parent `eventsEl` container
stretchZnumber0Move (translate) atropos container along the Z-axis on this value (in percentage). E.g. `50` value will move container +-50% of its height. Only for multiple Atropos, when multiple Atropos uses same parent `eventsEl` container
commonOriginbooleantrueWill dynamically set `transform-origin` for all Atropos components with same parent to same point (usually pointer position). Only for multiple Atropos, when multiple Atropos uses same parent `eventsEl` container
shadowbooleantrueEnables shadow
shadowOffsetnumber50Shadow offset, basically shadow element's translateZ value
shadowScalenumber1Shadow scale factor
highlightbooleantrueEnables highlight
onEnterfunctionCallback function will be fired when Atropos activated (on hover)
onLeavefunctionCallback function will be fired when Atropos deactivated (on pointer out)
onRotatefunction(x, y)Callback function will be fired on rotate. As arguments accepts x and y rotation angles

For example:

const myAtropos = Atropos({
el: '.my-atropos',
activeOffset: 40,
shadowScale: 1.05,
onEnter() {
console.log('Enter');
},
onLeave() {
console.log('Leave');
},
onRotate(x, y) {
console.log('Rotate', x, y);
}
});

Instance Properties

After we initialize Atropos we have its initialized instance with some helpful methods and properties:

NameTypeDescription
elHTMLElementMain container HTML element
isActivebooleanIndicates whether the Atropos is active (hovered) or not
paramsobjectAtropos parameters used for initialization (extended with defaults)
destroy()functionMethod to destroy the Atropos and detach all event listeners
destroyedbooleanIndicates whether the Atropos was destroyed or not

For example:

// init Atropos
const myAtropos = Atropos({
el: '.my-atropos',
activeOffset: 40,
});
setTimeout(() => {
// destroy it when needed
myAtropos.destroy();
}, 10000)

Control Elements Offsets

Atropos uses special data- attributes to control elements offset (parallax effect):

  • data-atropos-offset - controls element offset/translate in percentage.

    For example:
    • data-atropos-offset="5" means that element will move 5% of its size on max rotate angles.
    • data-atropos-offset="-5" means that element will move -5% of its size on max rotate angles.

    Basically if you want the element to appear closer (be in front of the scene), then this value should be positive. And if you want the element to appear in the distance (be behind the scene), then this value should be negative.

  • data-atropos-opacity - controls element opacity.
    For example:
    • data-atropos-opacity="0;1" - means element's opacity will change from 0 (on initial state) and up to 1 (on max rotate angles).
    • data-atropos-opacity="0.1;0.8" - means element's opacity will change from 0.1 (on initial state) and up to 0.8 (on max rotate angles).
    • data-atropos-opacity="1;0" - means element's opacity will change from 1 (on initial state) and down to to 0 (on max rotate angles).

For example:

<div class="atropos">
<div class="atropos-scale">
<div class="atropos-rotate">
<div class="atropos-inner">
<!--
Element with negative offset will move in reverse direction,
making it appear behind the scene
-->
<img src="image-bg.png" data-atropos-offset="-5" />
<!--
Element with no offset will not move
-->
<img src="image-middle.png" data-atropos-offset="0" />
<!--
Element with positive offset will move in same direction,
making it appear in front of the scene
-->
<img src="image-front.png" data-atropos-offset="5" />
</div>
</div>
</div>
</div>

What's next?

As you see it is easy to integrate Atropos into your website or app. So here are your next steps: