Motion.js


Documentation v1.0.0


What is Motion.js?


Motion.js is a global time engine for CSS-native animation. It provides a shared clock that updates CSS variables once per second, while CSS handles smooth 60fps interpolation. Motion.js supplies the timing source then CSS performs the animation.
Using nothing but CSS, HTML, and Motion.js, you can build synced, procedural, and time-driven motion systems. Motion.js is extremely lightweight and written in pure JavaScript with zero dependencies.
Motion.js is designed for advanced motion systems, game loops, and coordinated effects. Pair it with Trig.js for scroll-reactive motion and Cursor.js for cursor-reactive motion.


Dataset Outputs

When data-motion-var="true" is enabled, Motion.js automatically updates dataset attributes on the element every tick. These values update in increments of 10 and can be used directly in CSS for conditional styling.

        <div class="demoBox"
            data-motion
            data-motion-var="true"
            data-motion-duration="3000">
        </div>
                

During runtime, Motion.js will output attributes like:

data-motion-var="40"
data-motion-time="1200"
data-motion-loop="2"
data-motion-bounce="80"
data-motion-noise="30"

You can use these values in CSS attribute selectors:

        .demoBox[data-motion-var="50"] {
            background: #3b82f6;
        }

        .demoBox[data-motion-bounce="80"] {
            transform: scale(1.1);
        }

        .demoBox[data-motion-noise="30"] {
            filter: brightness(1.2);
        }
                

This allows you to build CSS-only logic based on time, loops, bounce, noise, and progress with no JavaScript required.

How To Install?

All you need to do is add the dist motion.min.js file into your projects JS folder and add the following code with your motion.js location as the src. Put this code in to your head HTML tags. Download Motion.js here or use npm.

                            <script src="/js/motion.min.js"></script>
                    

Or just add a CDN instead

                        <script src="https://cdn.jsdelivr.net/npm/@idevgames/motion-js/dist/motion.min.js"></script>
                    

How To Use?

To activate motion.js add the data attribute "data-motion" or a class "enable-motion" to your html element. Motion.js will automatically start updating time-reactive CSS variables on that element once it enters the viewport.

                            <div data-motion data-motion-var="true"> </div>
                    
                        .element{
                            opacity: calc(var(--motion-progress) / 100);
                            transform: rotate(var(--motion-deg));
                        }
                    

Time-Based Animations

Motion.js calculates time-based progress and creates CSS variables that you can use with CSS transform, opacity, colors, etc.

                            <div class="element" data-motion data-motion-var="true" data-motion-duration="2000"> </div>
                    
                            .element{ transform: translateX( var(--motion-progress) ); }
                    

The CSS variables you can use by adding data-motion-var="true" are:

--motion-time
--motion-time-reverse
--motion-progress
--motion-progress-reverse
--motion-loop
--motion-loop-reverse
--motion-bounce
--motion-bounce-reverse
--motion-noise
--motion-noise-reverse
--motion-deg
--motion-deg-reverse

The data attribute will also update in increments of 10 so you can use CSS attribute selectors like [data-motion-var="50"]{ } for more control.


Animation State

Motion.js creates classes of "motion-playing" and "motion-paused" on elements, as well as progress checkpoint classes like "motion-progress-25", "motion-progress-50", "motion-progress-75" on the body element.


Special Variables

Motion.js provides special variables for organic motion: --motion-bounce creates a ping-pong effect, and --motion-noise generates pseudo-random values for natural-looking animations.


Data Attributes

You can use the below data attributes for additional features

                            <div id="yourelement" data-motion data-motion-var="true" data-motion-duration="1000" data-motion-delay="0" data-motion-min="0" data-motion-max="100" data-motion-global="false"> </div>
                        

Manual Control

Pause and play Motion.js from the console for DevTools workflow:

                            // Pause all time updates
                            motion.pause();

                            // Resume time updates
                            motion.play();
                        

This is especially useful when inspecting CSS in DevTools - pause the clock, make your changes, then resume.


BE CREATIVE
WITH YOUR CSS

Check out the code of the documentation as an example.