Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Cuberto/mouse-follower
A powerful javascript library to create amazing and smooth effects for the mouse cursor on your website.
https://github.com/Cuberto/mouse-follower
Last synced: 5 days ago
JSON representation
A powerful javascript library to create amazing and smooth effects for the mouse cursor on your website.
- Host: GitHub
- URL: https://github.com/Cuberto/mouse-follower
- Owner: Cuberto
- License: mit
- Created: 2022-03-29T15:06:19.000Z (over 2 years ago)
- Default Branch: dev
- Last Pushed: 2023-10-23T22:55:31.000Z (about 1 year ago)
- Last Synced: 2024-04-25T01:08:20.210Z (7 months ago)
- Language: JavaScript
- Size: 68.4 KB
- Stars: 686
- Watchers: 8
- Forks: 58
- Open Issues: 24
-
Metadata Files:
- Readme: README.MD
Awesome Lists containing this project
README
# Cuberto Mouse Follower
A powerful javascript library to create amazing and smooth effects for the mouse cursor on your website.
## Dependencies
GSAP v3 (https://greensock.com/gsap/)
## Quick start
### Install from NPM
Mouse Follower requires GSAP library to work.
```
npm install gsap --save
npm install mouse-follower --save
```
Import GSAP and Mouse Follower and initialize it:
```js
import MouseFollower from "mouse-follower";
import gsap from "gsap";
MouseFollower.registerGSAP(gsap);
const cursor = new MouseFollower();
```
Don't forget to import the cursor styles from `/src/scss/index.scss` into your main scss file:
```scss
@import "cursor";
```
### Use from CDN
If you don't want to include Mouse Follower files in your project, you can use it from CDN.
The following files are available:
```html
```
Mouse Follower requires GSAP library to work. You need to import it before the Mouse Follower if you didn't have it before:
```html
var cursor = new MouseFollower();
```
## Options
You can configure Mouse Follower via options:
```js
const cursor = new MouseFollower({
container: '.mf-container',
speed: 0.3
});
```
The following options with defaults are available:
```js
const cursor = new MouseFollower({
el: null,
container: document.body,
className: 'mf-cursor',
innerClassName: 'mf-cursor-inner',
textClassName: 'mf-cursor-text',
mediaClassName: 'mf-cursor-media',
mediaBoxClassName: 'mf-cursor-media-box',
iconSvgClassName: 'mf-svgsprite',
iconSvgNamePrefix: '-',
iconSvgSrc: '',
dataAttr: 'cursor',
hiddenState: '-hidden',
textState: '-text',
iconState: '-icon',
activeState: '-active',
mediaState: '-media',
stateDetection: {
'-pointer': 'a,button',
'-hidden': 'iframe'
},
visible: true,
visibleOnState: false,
speed: 0.55,
ease: 'expo.out',
overwrite: true,
skewing: 0,
skewingText: 2,
skewingIcon: 2,
skewingMedia: 2,
skewingDelta: 0.001,
skewingDeltaMax: 0.15,
stickDelta: 0.15,
showTimeout: 20,
hideOnLeave: true,
hideTimeout: 300,
hideMediaTimeout: 300
});
```
| Name | Type | Description |
| :--- | :---: | :--- |
| `el` | `string` | `HTMLElement` | Existed cursor element. If not specified, the cursor will be created automatically. |
| `container` | `string` | `HTMLElement` | Cursor container. Body by default. |
| `className` | `string` | Cursor root element class name. |
| `innerClassName` | `string` | Inner element class name. |
| `textClassName` | `string` | Text element class name. |
| `mediaClassName` | `string` | Media element class name. |
| `mediaBoxClassName` | `string` | Media inner element class name. |
| `iconSvgClassName` | `string` | SVG sprite class name. |
| `iconSvgNamePrefix` | `string` | SVG sprite class name prefix of icon. |
| `iconSvgSrc` | `string` | SVG sprite source. If you are not using SVG sprites leave this blank. |
| `dataAttr` | `string` | `null` | Name of data attribute for changing cursor state directly in HTML markdown. Uses an event delegation. |
| `hiddenState` | `string` | Hidden class name state. |
| `textState` | `string` | Text class name state. |
| `iconState` | `string` | Icon class name state. |
| `activeState` | `string` | `null` | Active (mousedown) class name state. Set `false` to disable. |
| `mediaState` | `string` | Media (image/video) class name state. |
| `visible` | `boolean` | Is cursor visible by default. |
| `visibleOnState` | `boolean` | Automatically show/hide cursor when state added. Can be useful when implementing a hidden cursor follower. |
| `stateDetection` | `object` | `null` | Allow to set predefined states for different elements on page. Uses an event delegation. |
| `speed` | `number` | Cursor movement speed. |
| `ease` | `string` | Timing function of cursor movement. See [gsap easing](https://greensock.com/docs/v3/Eases). |
| `overwrite` | `boolean` | Overwrite or remain cursor position when `mousemove` event happened. See [gsap overwrite modes](https://greensock.com/conflict/). |
| `skewing` | `number` | Default "skewing" factor. |
| `skewingText` | `number` | Skew effect factor in a text state. Set `0` to disable skew in this mode. |
| `skewingIcon` | `number` | Skew effect factor in a icon state. Set `0` to disable skew in this mode. |
| `skewingMedia` | `number` | Skew effect factor in a media (image/video) state. Set `0` to disable skew in this mode. |
| `skewingDelta` | `number` | Skew effect base delta. Set `0` to disable skew in this mode. |
| `skewingDeltaMax` | `number` | Skew effect max delta. Set `0` to disable skew in this mode. |
| `stickDelta` | `number` | Stick effect delta. |
| `showTimeout` | `number` | Delay before show. May be useful for the spawn animation to work properly. |
| `hideOnLeave` | `boolean` | Hide the cursor when mouse leave container. |
| `hideTimeout` | `number` | Hiding delay. Should be equal to the CSS hide animation time. |
| `initialPos` | `array` | Array (x, y) of initial cursor position. |
## Advanced usage
### Show or hide cursor
These basic methods allow you to show and hide the cursor:
```js
const cursor = new MouseFollower();
const el = document.querySelector('.my-element');
el.addEventListener('mouseenter', () => {
cursor.hide();
});
el.addEventListener('mouseleave', () => {
cursor.show();
});
```
or via data attribute:
```html
Hover me to hide cursor!
```
### Toggle cursor state
A state is essentially a class that applies to the root element of the cursor. You can change the appearance of the
cursor using CSS (see `cursor.scss`).
To set/unset state use methods:
```js
const cursor = new MouseFollower();
const el = document.querySelector('.my-element');
el.addEventListener('mouseenter', () => {
cursor.addState('-inverse'); // you can pass multiple states separated by whitespace
});
el.addEventListener('mouseleave', () => {
cursor.removeState('-inverse');
});
```
or via data attribute:
```html
Hover me to inverse cursor!
```
### State detection
You can customize the list of states for all elements on the page:
```js
const cursor = new MouseFollower({
stateDetection: {
'-pointer': 'a,button',
'-opaque': '.my-image',
'-hidden': '.my-input'
}
});
```
```html
On this element cursor will be in pointer state
On this element cursor will be in opaque state
On this element cursor will be hidden
```
Note: State detection feature uses an event delegation. Do not create large amount rules and complex selectors to avoid
performance problems. It is recommended to disable this in projects with a large number of nested DOM elements. This
also applies to binding via data attribute.
To fully disable event delegation:
```js
const cursor = new MouseFollower({
stateDetection: false,
dataAttr: false
});
```
### Text mode
To display text in the cursor use this method:
```js
const cursor = new MouseFollower();
const el = document.querySelector('.my-element');
el.addEventListener('mouseenter', () => {
cursor.setText('Hello!');
});
el.addEventListener('mouseleave', () => {
cursor.removeText();
});
```
or via data attribute:
```html
Hover me!
```
### Icon mode
If you use SVG spritesheet in your project and want to display them in the cursor, then you can use this method. In this
case, you need to specify the path to the SVG sprite in the options and set class names.
```js
const cursor = new MouseFollower({
iconSvgSrc: '/assets/img/sprites/svgsprites.svg',
iconSvgClassName: 'my-spritesheet',
iconSvgNamePrefix: '-',
});
const el = document.querySelector('.my-element');
el.addEventListener('mouseenter', () => {
cursor.setIcon('arrow-left');
});
el.addEventListener('mouseleave', () => {
cursor.removeIcon();
});
```
or via data attribute:
```html
Hover me!
```
### Image mode
This method allows you to show any picture in the cursor:
```js
const cursor = new MouseFollower();
const el = document.querySelector('.my-element');
el.addEventListener('mouseenter', () => {
cursor.setImg('/img/example.png')
});
el.addEventListener('mouseleave', () => {
cursor.removeImg()
});
```
or via data attribute:
```html
Hover me to show image!
```
### Video mode
You can also play videos:
```js
const cursor = new MouseFollower();
const el = document.querySelector('.my-element');
el.addEventListener('mouseenter', () => {
cursor.setVideo('/video/example.mp4');
});
el.addEventListener('mouseleave', () => {
cursor.removeVideo();
});
```
or via data attribute:
```html
Hover me to show movie!
```
### Sticky effect
This method allows you to attach the cursor to an element with a magnet effect. This only works correctly with fixed
elements on the page.
```js
const cursor = new MouseFollower();
const box = document.querySelector('.my-fixed-box');
const el = document.querySelector('.my-fixed-element');
box.addEventListener('mouseenter', () => {
cursor.setStick(el);
});
box.addEventListener('mouseleave', () => {
cursor.removeStick();
});
```
or via data attribute:
```html
Hover me to stick cursor!
```
You can also pass element selector to data attribute:
```html
Hover me to stick cursor!
```
### Skewing effect
The skew effect is the distortion of the cursor when moving. It looks good with round cursors.
```js
const cursor = new MouseFollower();
const el = document.querySelector('.my-element');
el.addEventListener('mouseenter', () => {
cursor.setSkewing(3);
});
el.addEventListener('mouseleave', () => {
cursor.removeSkewing();
});
```
### Hidden cursor
In this example, the cursor is initialized hidden by default and only appears on the desired element.
```js
const cursor = new MouseFollower({
visible: false
});
const el = document.querySelector('.my-element');
el.addEventListener('mouseenter', () => {
cursor.show();
cursor.setText('Surprise!');
});
el.addEventListener('mouseleave', () => {
cursor.removeText();
cursor.hide();
});
```
or via data attribute:
```html
Hover me to show cursor!
```
### Destroy cursor instance
Destroy the cursor completely and remove all event listeners.
```js
const cursor = new MouseFollower();
cursor.destroy();
```
## Events
Mouse Follower comes with a useful events you can listen. Events can be assigned in this way:
```js
const cursor = new MouseFollower();
cursor.on('show', () => {
console.log('cursor appear');
});
```
You can also delete an event that you no longer want to listen in these ways:
```js
cursor.off('show');
cursor.off('show', myHandler);
```
| Name | Arguments | Description |
| :--- | :--- | :--- |
| `show` | `(cursor)` | Event will be fired when the show state is entered. |
| `hide` | `(cursor)` | Event will be fired when the hidden state is entered. |
| `addState` | `(cursor, state)` | Event will be fired when the state is added. |
| `removeState` | `(cursor, state)` | Event will be fired when the state is removed. |
| `render` | `(cursor)` | Event will be fired on each render tick. |
| `destroy` | `(cursor)` | Event will be fired when the instance is destroyed. |
## Examples of use
- [Cuberto](https://cuberto.com/): Leading digital agency.
- [Potion](https://www.sendpotion.com/): Video email for top sales professionals.
- [Wickret](https://wickret.cuberto.com/): 100% digital bank designed for you.
- [Papumba](https://www.papumba.com/): Educational platform for kids.
- [Safe Security](https://www.safe.security/): Cyber Risk Quantification For Enterprises.
## License
[The MIT License (MIT)](LICENSE)