cursix v1.1.4

Cursix

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

Cursix requires GSAP library to work.

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

Import GSAP and Cursix and initialize it:

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:

@import "cursor";

Use from CDN

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

The following files are available:

<link rel="stylesheet" href="https://unpkg.com/cursix/dist/cursix.min.css">

<script src="https://unpkg.com/cursix/dist/cursix.min.js"></script>

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

<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.10.4/gsap.min.js"></script>
<script src="https://unpkg.com/cursix/dist/cursix.min.js"></script>
<script>
    var cursor = new Cursix();
</script>

Options

You can configure Cursix via options:

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

The following options with defaults are available:

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
});

Advanced usage

Show or hide cursor

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

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

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

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

or via data attribute:

<div data-cursor="-hidden">Hover me to hide cursor!</div>

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:

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:

<div data-cursor="-inverse">Hover me to inverse cursor!</div>

State detection

You can customize the list of states for all elements on the page:

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

<a>On this element cursor will be in pointer state</a>
<div class="my-image">On this element cursor will be in opaque state</div>
<div class="my-input">On this element cursor will be hidden</div>

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:

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

Text mode

To display text in the cursor use this method:

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:

<div data-cursor-text="Hello!">Hover me!</div>

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.

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:

<div data-cursor-icon="arrow-left">Hover me!</div>

Image mode

This method allows you to show any picture in the cursor:

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:

<div data-cursor-img="/img/example.png">Hover me to show image!</div>

Video mode

You can also play videos:

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:

<div data-cursor-video="/video/example.mp4">Hover me to show movie!</div>

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.

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:

<div data-cursor-stick>Hover me to stick cursor!</div>

You can also pass element selector to data attribute:

<div data-cursor-stick="#stick-me">Hover <div id="stick-me">me</div> to stick cursor!</div>

Skewing effect

The skew effect is the distortion of the cursor when moving. It looks good with round cursors.

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

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:

<div data-cursor-show data-cursor-text="Surprise!">Hover me to show cursor!</div>

Destroy cursor instance

Destroy the cursor completely and remove all event listeners.

const cursor = new Cursix();

cursor.destroy();

Events

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

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:

cursor.off('show');
cursor.off('show', myHandler);

License

The MIT License (MIT)