Create Custom Interactive Mouse Cursors with Cursix and GSAP

Preview:

Description:

Cursix is a JavaScript library that transforms standard mouse cursors into custom, animated, interactive elements. Smooth animations are based on the GSAP library.

You can display images, text, icons, or videos in your cursor, apply magnetic effects to fixed elements, and add smooth skewing animations during cursor movement.

This library can be helpful for web developers looking to add a layer of interactivity to their projects. For instance, an art gallery website could display a magnifying glass icon as the cursor when hovering over artwork, hinting at a zoom feature. An e-commerce site could change the cursor to a shopping cart icon when hovering over “Add to Cart” buttons.

See It In Action:

How to use it:

1. Install Cursix and its dependency, GSAP library.

# NPM
$ npm install gsap cursix

2. Import the libraries in your JavaScript:

import Cursix from "cursix";
import gsap from "gsap";
// Import the default styles in your SCSS file:
@import "cursor";

3. Register GSAP with Cursix:

Cursix.registerGSAP(gsap);

4. Alternatively, import the following JavaScript and CSS files directly into your web page.

<link rel="stylesheet" href="/dist/cursix.min.css">
<script src="/path/to/gsap.min.js"></script>
<script src="/dist/cursix.min.js"></script>

5. Initialize the Cursix to activate a basic custom cursor.

var cursor = new Cursix();

6. Control cursor visibility on specific elements:

// hide
cursor.hide();
// show
cursor.show();

// You can achieve the same using the data-cursor attribute:
<div data-cursor="-hidden">Hover to hide</div>

7. Show custom text within the cursor:

// Set text
cursor.setText('CSSScript');
// Remove text
cursor.removeText();

// Or use the data-cursor-text attribute:
<div data-cursor-text="CSSScript!">Hover Me</div>

8. Show your image within the cursor:

// Set image
cursor.setImg('/path/to/image.png');
// Remove image
cursor.removeImg();

// Or use the data-cursor-img attribute:
<div data-cursor-img="/path/to/image.png">Hover Me</div>

9. Embed a video within the cursor:

// Set video
cursor.setVideo('/path/to/video.mp4');
// Remove video
cursor.removeVideo();

// Or use the data-cursor-video attribute:
<div data-cursor-video="/path/to/video.mp4">Hover Me</div>

10. Display icons from your SVG sprite sheet in the cursor. Configure the sprite path and class names:

const cursor = new Cursix({
  iconSvgSrc: '/path/to/svgsprites.svg',
  iconSvgClassName: 'my-spritesheet',
  iconSvgNamePrefix: '-',
});
// Set icon
cursor.setIcon('arrow-left');
// Remove icon
cursor.removeIcon();

// Or use the cursor-icon attribute:
<div data-cursor-icon="arrow-left">Hover Me</div>

11. Attach the cursor to a fixed element for a “magnet” effect:

// Set stick
cursor.setStick(el);
// Remove stick
cursor.removeStick();

// Or use the data-cursor-stick attribute:
<div data-cursor-stick>Hover Me</div>
<div data-cursor-stick="#stick-me">Hover <div id="stick-me">Me</div></div>

12. Distort the cursor during movement for a dynamic feel. This works best with round cursors.

// Set skewing
cursor.setSkewing(5);
// Remove skewing
cursor.removeSkewing();

13. The following options allow fine-grained control over the cursor’s appearance, behavior, and responsiveness.

const cursor = new Cursix({
  // Existed cursor element. If not specified, the cursor will be created automatically.
  el: null,
  // Cursor container. Body by default.
  container: document.body,
  // Cursor root element class name.
  className: 'mf-cursor',
  // Inner element class name.
  innerClassName: 'mf-cursor-inner',
  // Text element class name.
  textClassName: 'mf-cursor-text',
  // Media element class name.
  mediaClassName: 'mf-cursor-media',
  // Media inner element class name.
  mediaBoxClassName: 'mf-cursor-media-box',
  // SVG sprite class name.
  iconSvgClassName: 'mf-svgsprite',
  // SVG sprite class name prefix of icon.
  iconSvgNamePrefix: '-',
  // SVG sprite source. If you are not using SVG sprites leave this blank.
  iconSvgSrc: '',
  // Name of data attribute for changing cursor state directly in HTML markdown. Uses an event delegation.
  dataAttr: 'cursor',
  // Hidden class name state.
  hiddenState: '-hidden',
  // Text class name state.
  textState: '-text',
  // Icon class name state.
  iconState: '-icon',
  // Active (mousedown) class name state. Set false to disable.
  activeState: '-active',
  // Media (image/video) class name state.
  mediaState: '-media',
  // Allow to set predefined states for different elements on page. Uses an event delegation.
  stateDetection: {
      '-pointer': 'a,button',
      '-hidden': 'iframe'
  },
  // Is cursor visible by default.
  visible: true,
  // Automatically show/hide cursor when state added. Can be useful when implementing a hidden cursor follower.
  visibleOnState: false,
  // Cursor movement speed.
  speed: 0.55,
  // Timing function of cursor movement. See gsap easing.
  ease: 'expo.out',
  // Overwrite or remain cursor position when mousemove event happened. See gsap overwrite modes.
  overwrite: true,
  // Default "skewing" factor.
  skewing: 0,
  // Skew effect factor in a text state. Set 0 to disable skew in this mode.
  skewingText: 2,
  // Skew effect factor in a icon state. Set 0 to disable skew in this mode.
  skewingIcon: 2,
  // Skew effect factor in a media (image/video) state. Set 0 to disable skew in this mode.
  skewingMedia: 2,
  // Skew effect base delta. Set 0 to disable skew in this mode.
  skewingDelta: 0.001,
  // Skew effect max delta. Set 0 to disable skew in this mode.
  skewingDeltaMax: 0.15,
  // Stick effect delta.
  stickDelta: 0.15,
  // Delay before show. May be useful for the spawn animation to work properly.
  showTimeout: 20,
  // Hide the cursor when mouse leave container.
  hideOnLeave: true,
  // Hiding delay. Should be equal to the CSS hide animation time.
  hideTimeout: 300,
  // Hiding delay for media elements.
  hideMediaTimeout: 300
  
});

14. More API Methods:

// Dynamically add or remove states:
cursor.addState('-inverse');
cursor.removeState('-inverse');
// Destroy the Cursix instance:
cursor.destroy();

15. Event handlers.

// Fires when the cursor becomes visible
cursor.on('show', (cursor) => {
  console.log('cursor appearance');
});
// Fires when the cursor becomes hidden
cursor.on('hide', (cursor) => {
  console.log('cursor hidden');
});
// Fires when a state is added to the cursor.
// The `cursor` argument is the Cursix instance, and the `state` argument is the name of the state that was added (e.g., '-text', '-icon').
cursor.on('addState', (cursor, state) => {
  console.log(`state "${state}" added`);
});
// Fires when a state is removed from the cursor.
// The `cursor` argument is the Cursix instance, and the `state` argument is the name of the state that was removed.
cursor.on('removeState', (cursor, state) => {
  console.log(`state "${state}" removed`);
});
// Fires on each animation frame where the cursor's position or appearance is updated.
// This can be useful for performing actions on every tick of the cursor animation.
// The `cursor` argument is the Cursix instance.
cursor.on('render', (cursor) => {
});
// Fires when the `destroy()` method is called on the Cursix instance.
// The `cursor` argument is the Cursix instance.
cursor.on('destroy', (cursor) => {
  console.log('cursix instance destroyed');
});