# CartFlow
[](SHOWCASE.md)
[](https://nassiry.github.io/cartflow/)
**CartFlow** is a lightweight, modern JavaScript library to animate items moving to a shopping cart. It supports Node.js, browser environments, and UMD/ES module formats.
- ✨ Smooth "Add to Cart" animations
- 🔈 Optional sound effect support
- 🛒 Optional cart "shake" effect
- ⚙️ Fully customizable via configuration options
- 🌍 Works in modern browsers and Node.js
- 📚 Typed API for great IDE experience (TypeScript definitions included)
- ⚡ Uses GSAP if available, otherwise falls back gracefully
## Table Of Contents
1. [Installation](#installation)
- [Install with npm](#1-install-with-npm)
- [Using a `
```
> Or use your own hosted file if needed: ``.
## Demo
See CartFlow in action here: [Live Demo](https://nassiry.github.io/cartflow/)
> Try adding items to the cart and watch the smooth animation!
## Usage
- ### 1. In Node.js / TypeScript / ESM
```javascript
// CommonJS (Node.js)
const CartFlow = require('cartflow');
// ES Module or TypeScript
import CartFlow from 'cartflow';
```
- ### 2. Quick Example
```javascript
const animation = new CartFlow({
cartSelector: ".shopping-cart",
buttonSelector: ".add-to-cart",
onComplete: (item) => {
console.log("Item successfully animated to the cart!", item);
},
onCartShake: (cart) => {
console.log("Cart shake effect completed!", cart);
},
soundEffect: "click-sound.mp3",
});
```
## Configuration Options
| Option | Type | Default | Description |
| ------------- | ------------- | -------- | ------ |
| `cartSelector` | `string` | `.shopping-cart` | CSS selector for the shopping cart element. |
| `buttonSelector` | `string` | `.add-to-cart` | CSS selector for the "Add to Cart" buttons. |
| `itemSelector` | `string` | `.item` | CSS selector for the item container. |
| `imageSelector` | `string` | `img` | CSS selector for the item's image.|
| `animationDuration` | `number` | `1000` | Duration of the animation in milliseconds. |
| `easing` | `string` | `ease-in-out` | Easing function for the animation. |
| `shakeEffect` | `boolean` | `true` | Enable or disable the cart shake effect. |
| `soundEffect` | `string or Audio` | `null` | URL or Audio object for a sound effect. |
| `onComplete` | `function` | `null` | Callback function after the animation completes, receives the affected item element. |
| `onCartShake` | `function` | `null` | Callback function after the cart shake effect, receives the cart element. |
### Browser & Nodejs Compatibility
Chrome | Firefox | Safari | Opera | Edge | Nodejs
--- | --- | --- | --- | --- | --- |
Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔
## Built With Cartflow.js
See how others are using this library in our [SHOWCASE.md](SHOWCASE.md).
_Using this library? [Add your project](SHOWCASE.md)_
## Contributing
We welcome contributions! Please read the [Contributions Guid](CONTRIBUTING.md) to get started.
## Changelog
See [Changelog](CHANGELOG.md) for full release history and version details.
## License
This package is open-source software licensed under the [MIT license](LICENSE).