gravityjs-animations

v1.0.0

Published

a month ago

A UI animation and styling framework for making animations behave like real life objects in Earth's gravity

0High
0Medium
0Low

skwrn

gravity physics animation ui animation-library

GravityJS Animations provides two complementary physics systems for the web:

| System | What it does | Entry point | |---|---|---| | UI Components | Spring-animated buttons, cards, accordions, alerts, and more - steered by data-gravity-* attributes | initComponents() | | Gravity Engine | Newtonian falling / bouncing DOM elements with configurable mass, elasticity, and friction | initGravity() / GravityEngine |

No dependencies. Zero configuration required. Works with vanilla HTML and is framework-compatible with React, Vue, and Angular via data-gravity-* attributes.

Installation

npm

npm install gravityjs-animations

CDN

<script src="https://unpkg.com/gravityjs-animations@latest/dist/gravityjs.umd.js"></script>

When loaded via this UMD bundle, all exports are available on the global window.GravityJS object.

From npm, GravityJS Animations exposes a single 'gravityjs-animations' entrypoint with ESM and CommonJS builds plus bundled TypeScript types; the build is tested to ensure these imports resolve correctly.

Quick Start

Vanilla HTML via CDN

<!DOCTYPE html>
<html>
<body>

  <!-- Physics spring hover on a button -->
  <button data-gravity-button>Hover me</button>

  <!-- Card that lifts on hover with animated shadow -->
  <div data-gravity-card style="padding:24px;border-radius:12px;background:#fff;">
    <h3>Card Title</h3>
    <p>Hover to lift with a spring.</p>
  </div>

  <!-- Accordion with physics open/close -->
  <div data-gravity-accordion>
    <button>What is GravityJS?</button>
    <div class="accordion-content">
      <div>A physics-based animation library for the web applications. Use it in Angular, Vue, React or vanilla HTML.</div>
    </div>
  </div>

	  <script src="https://unpkg.com/gravityjs-animations@latest/dist/gravityjs.umd.js"></script>
  <script>
    GravityJS.initComponents(); // scan DOM and activate all data-gravity-* elements
  </script>

</body>
</html>

Via npm (ESM / TypeScript)

import { initComponents } from 'gravityjs-animations';

// Call once after the DOM is ready - returns a teardown function
const teardown = initComponents();

// Clean up all instances and the MutationObserver (e.g. on SPA route change)
// teardown();

UI Components Overview

See UI Components Reference for the full UI Components documentation.

Gravity Engine

See Gravity Engine for detailed usage.

Framework Integration

See Framework Integration for React, Vue, and Angular examples.

Physics Tuning

See Physics Tuning for tuning recipes.

Material Hints

See Material Hints for material presets.

Advanced Features

See Advanced Features for motion blur, text animation, scoped init, and more.

API Reference

See API Reference for function and type details.

CSS Utilities

See CSS Utilities for stylesheet usage.

Versioning

GravityJS Animations follows Semantic Versioning. The 1.x line indicates that the public gravityjs-animations package and CDN bundle APIs are considered stable: new features and bug fixes in 1.x will not intentionally break the behaviours documented in this README. Breaking changes will be released under a new major version (2.0.0, 3.0.0, ...).

License

Contact

Andrzej Skowron - [email protected]