https://github.com/mgks/fluid.js
A lightweight, zero-dependency fluid simulation for web that reacts to device motion.
https://github.com/mgks/fluid.js
accelerometer canvas fluid-simulation frontend gyroscope javascript motion-design nodejs npm-package physics ui-library
Last synced: 5 months ago
JSON representation
A lightweight, zero-dependency fluid simulation for web that reacts to device motion.
- Host: GitHub
- URL: https://github.com/mgks/fluid.js
- Owner: mgks
- License: mit
- Created: 2025-12-27T12:14:07.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-12-27T22:12:29.000Z (5 months ago)
- Last Synced: 2025-12-29T06:48:30.921Z (5 months ago)
- Topics: accelerometer, canvas, fluid-simulation, frontend, gyroscope, javascript, motion-design, nodejs, npm-package, physics, ui-library
- Language: JavaScript
- Homepage: https://mgks.github.io/fluid.js
- Size: 22.5 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# fluid.js
**A tiny, zero-dependency fluid simulation for the web that reacts to device motion.**
Most fluid simulations are heavy particle engines (100KB+). **fluid.js** is different. It uses a 2D spring-mass system coupled with inertial angular physics to simulate the *feeling* of liquid in a container.
It is designed for **UI Backgrounds**, **Loading States**, and **Interactive Cards**.
## Features
- **Micro-Library:** ~4KB (minified + gzipped).
- **Device Ready:** Reacts to Gyroscope/Accelerometer (Mobile) and Mouse/Slider (PC).
- **Inertial Physics:** Simulates "Slosh", momentum, and wall climbing (U-Shape).
- **Zero Dependencies:** Pure Vanilla JS. Works with React, Vue, Svelte, or plain HTML.
## Installation
```bash
npm install fluid.js
```
## Usage
### Vanilla JS / HTML
```html
import { Fluid } from 'fluid.js';
const fluid = new Fluid('#my-fluid-canvas', {
color: '#00aaff', // Hex color
tension: 0.01, // Surface tension
dampening: 0.02 // Ripple decay
});
// Set initial fill level (0 to 100)
fluid.setFill(50);
```
### React / Vue
```javascript
import { useEffect, useRef } from 'react';
import { Fluid } from 'fluid.js';
export default function LiquidCard() {
const canvasRef = useRef(null);
useEffect(() => {
const myFluid = new Fluid(canvasRef.current, {
color: '#ff4444'
});
myFluid.setFill(60);
}, []);
return ;
}
```
## Configuration
You can tune the liquid to feel like Water, Oil, or Jelly.
| Option | Default | Description |
| :--- | :--- | :--- |
| `color` | `#3b82f6` | The hex color of the liquid. |
| `tension` | `0.01` | Surface stiffness. Lower = more waves. |
| `dampening` | `0.02` | Friction. Lower = waves last longer. |
| `spread` | `0.25` | How fast ripples travel across the surface. |
| `inertia` | `0.96` | Momentum conservation. Higher = more slosh. |
| `wallClimb` | `2.5` | How high fluid climbs walls during rotation. |
### Presets
If you don't want to tune physics manually, copy these values:
**Water (Default)**
```javascript
{ tension: 0.01, dampening: 0.02, inertia: 0.96 }
```
**Oil / Honey**
```javascript
{ tension: 0.03, dampening: 0.1, inertia: 0.90 }
```
**Slime / Jelly**
```javascript
{ tension: 0.08, dampening: 0.05, inertia: 0.80 }
```
## Mobile Permissions (iOS)
On iOS 13+, you must request permission to access the Gyroscope. The browser **will not** let you access sensors automatically. You must trigger this from a button click (e.g., "Enable Gravity").
```javascript
// Run this inside a button click handler
if (typeof DeviceMotionEvent.requestPermission === 'function') {
DeviceMotionEvent.requestPermission()
.then(response => {
if (response === 'granted') {
// Sensors are now active, fluid.js will auto-detect them
}
})
.catch(console.error);
}
```
## License
MIT
> **{ github.com/mgks }**
>
> 
