Cotton.JS is a JavaScript library that allows you to make a mouse interaction animation easily.


Getting Started


Via npm

npm install cotton


<script src="[email protected]/lib/magnet-mouse.min.js"></script>

Manual download


ES modules

After Download the files from npm, all you need is typing the following code :

import Cotton from 'cotton'

Script tag include

Simply download (or using CDN) and include with a script tag.

<script src="cotton.js"></script>

Basic Usage


Create an element that you would like to animate.

<div id="#cotton-cursor"></div>


Style your element.

If you want to make a mouse-following element, you have to set the position property as fixed.

#cotton-cursor {
    position: fixed;
    z-index: 9;
    width: 20px;
    height: 20px;
    border-radius: 50%;
    pointer-events: none;
    background-color: #f9cabc;
    transform: translate(-20px, -20px);    /* move out from window before cotton init */


Initialize Cotton in JavaScript.

const cottonCursor = new Cotton('#cotton-cursor')



Cotton : which means the element that you initialize.
Models : which means the elements that would interact with your cotton.

All available parameters :

Name Type Default Description
scene string 'body' The animation will work when only the mouse is moving in the scene.
cottonInitClass string 'cotton-init' The cottonInitClass will be added when cotton is initialized, and will be removed when you call the stop() method.
cottonMovingClass string 'cotton-moving' The cottonMovingClass will be added when the mouse enter the scene, and will be removed when the mouse leave the scene.

cottonMovingClass will also be removed when you call the stop() method.

cottonActiveClass string 'cotton-active' The cottonActiveClass will be added on cotton when mouse enter the models, and will be removed mouse leave the models.
models string '.cotton-model' Define the elements that you want your cotton to interact with.
modelsActiveClass string 'model-active' The modelsActiveClass will be added on model when mouse enter the model, and will be removed mouse leave the model.
speed number 0.125 The lower the number, the greater the delay

The speed property must be > 0 and <= 1.
If this parameter is not specified, it will be set to default.

airMode boolean | object false By default, the cotton element will relative to the top left of the window when doing the transform.
If set to true, then cotton will do the transform relative to its own center point. And the following properties will be set automatically.

airMode: {
    resistance: 15,
    reverse: false
or you can just set an object with specified properties directly.

In airMode, the transform value will not increase if cotton is not in viewport.

airMode.resistance number 15 The higher the number, the less the transform.

The resistance property must be >= 1 and <= 100.
If this parameter is not specified, it will be set to default.
If set to 1, cotton will follow the mouse completely.

airMode.reverse boolean false By default, the airMode cotton will move forward to the mouse.
If set to true, the airMode cotton will move backward to the mouse.


After you initialize the cotton element, you can use the methods of its initialized instance in the variable. As the following example :

const cotton = new Cotton('#cotton-cursor')

// call the stop method of cotton

All available methods :

Methods Description
cotton.stop() Cancel the animation immediately.
The cotton element will not interact with the mouse. And the cottonInitClass will be removed when you call this method.
cotton.move() Restart the animation.
And the cottonInitClass will be added again when you call this method.
cotton.updateModels() This method will update the nodelist of models and also bind the callbacks that you defined automatically. It is very useful when you append new models or use AJAX.