Cursix

A powerful javascript library to create amazing and smooth effects for the mouse cursor on your website.

!demo

Dependencies

GSAP v3 (https://greensock.com/gsap/)

Quick start

$3

Cursix requires GSAP library to work.

``
npm install gsap --save
npm install cursix --save
`

Import GSAP and Cursix and initialize it:

`js
import Cursix from "cursix";
import gsap from "gsap";

Cursix.registerGSAP(gsap);

const cursor = new Cursix();
`

Don't forget to import the cursor styles from /src/scss/index.scss into your main scss file:

`scss
@import "cursor";
`

$3

If you don't want to include Cursix files in your project, you can use it from CDN.

The following files are available:

`html



`

Cursix requires GSAP library to work. You need to import it before the Cursix if you didn't have it before:

`html



`

Options

You can configure Cursix via options:

`js
const cursor = new Cursix({
container: '.mf-container',
speed: 0.3
});
`

The following options with defaults are available:

`js
const cursor = new Cursix({
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. |
| overwrite | boolean | Overwrite or remain cursor position when mousemove event happened. See gsap overwrite modes. |
| 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

$3

These basic methods allow you to show and hide the cursor:

`js
const cursor = new Cursix();
const el = document.querySelector('.my-element');

el.addEventListener('mouseenter', () => {
cursor.hide();
});

el.addEventListener('mouseleave', () => {
cursor.show();
});
`

or via data attribute:

`html


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 Cursix();
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


`js
const cursor = new Cursix({
stateDetection: {
'-pointer': 'a,button',
'-opaque': '.my-image',
'-hidden': '.my-input'
}
});
`

`html
On this element cursor will be in pointer state


`js
const cursor = new Cursix({
stateDetection: false,
dataAttr: false
});
`

$3

To display text in the cursor use this method:

`js
const cursor = new Cursix();
const el = document.querySelector('.my-element');

el.addEventListener('mouseenter', () => {
cursor.setText('Hello!');
});

el.addEventListener('mouseleave', () => {
cursor.removeText();
});
`

or via data attribute:

`html


`js
const cursor = new Cursix({
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


`js
const cursor = new Cursix();
const el = document.querySelector('.my-element');

el.addEventListener('mouseenter', () => {
cursor.setImg('/img/example.png')
});

el.addEventListener('mouseleave', () => {
cursor.removeImg()
});
`

or via data attribute:

`html


`js
const cursor = new Cursix();
const el = document.querySelector('.my-element');

el.addEventListener('mouseenter', () => {
cursor.setVideo('/video/example.mp4');
});

el.addEventListener('mouseleave', () => {
cursor.removeVideo();
});
`

or via data attribute:

`html


`js
const cursor = new Cursix();
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


`html


`js
const cursor = new Cursix();
const el = document.querySelector('.my-element');

el.addEventListener('mouseenter', () => {
cursor.setSkewing(3);
});

el.addEventListener('mouseleave', () => {
cursor.removeSkewing();
});
`

$3

In this example, the cursor is initialized hidden by default and only appears on the desired element.

`js
const cursor = new Cursix({
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


`js
const cursor = new Cursix();

cursor.destroy();
`

Events

Cursix comes with a useful events you can listen. Events can be assigned in this way:

`js
const cursor = new Cursix();

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. |

License

The MIT License (MIT)