Installation

1. Prepare Cursor Images

   AnimeCursor is a JavaScript library that can automatically build animated virtual cursors based on user-defined settings, but it does not provide cursor images itself. Therefore, before using AnimeCursor, you need to prepare your cursor images.

   AnimeCursor supports two methods for implementing animated cursors: sprite sheet animation and GIF animation.
   Of course, in addition to animated cursors, AnimeCursor also supports static cursors.

   • Sprite Sheet Animation

     Sprite sheet animation is the recommended method for AnimeCursor because it offers better visual presentation and more creative freedom compared to GIF images, and makes it easier to implement ping-pong loops. Future updates to AnimeCursor will also focus on features for sprite sheet animated cursors.

     Currently (as of v0.2.0), AnimeCursor's sprite sheet animation only supports single-row sprite sheets. Please ensure your sprite sheet layout meets this requirement; if it's not a single-row sprite sheet, please edit it into a single row.

     AnimeCursor will automatically generate CSS frame animations based on your settings. However, please note that currently (as of v0.2.0), AnimeCursor automatically distributes frame duration evenly based on the set animation duration and frame count. This means every frame is a keyframe with no interpolation frames. If you have frames that need to last longer than others, you'll need to place multiple duplicate frames in the sprite sheet, which increases the file size. Therefore, if you have longer-lasting frames, consider whether to switch to GIF animation to reduce loading time.

     We will add support for multi-row sprite sheets and custom frame duration in future versions (due to backward-incompatible API updates, the version is expected to be v1.0.0).

   • GIF Animation

     AnimeCursor's working principle also allows GIF animations to serve as animated cursor images. If your animated cursor has long static states, consider using GIF animation.

     For GIF animations, AnimeCursor has no special requirements. However, please note that the presentation of GIF animations and sprite sheet animations will differ, so choose according to your needs.

   • Pixel Art Images

     For pixel-style cursors, whether using sprite sheet animation or GIF animation, AnimeCursor recommends using pixel art at its original size (for example, a 16px × 16px pixel art does not need to be scaled to 64px × 64px in image editing software before being loaded by AnimeCursor). AnimeCursor supports scaling cursors and pixelated rendering. By combining these two features, you can achieve animated cursor effects with very small file sizes, greatly saving page loading time.

2. Deploy AnimeCursor

   • CDN

     Get the latest version of AnimeCursor directly via jsDelivr's npm CDN

     <script src="https://cdn.jsdelivr.net/npm/anime-cursor/dist/anime-cursor.umd.min.js"></script>

     Or get a specific version via jsDelivr's GitHub release CDN

     <script src="https://cdn.jsdelivr.net/gh/ShuninYu/anime-cursor@v0.3.1/dist/anime-cursor.umd.min.js"></script>

   • npm

     npm i anime-cursor

     import AnimeCursor from 'anime-cursor';
     new AnimeCursor({...});

   • Host Yourself

     AnimeCursor has a small file size, so if jsDelivr's CDN is slow for your region, you can also choose to deploy AnimeCursor locally

     <!-- Remember to modify the src to your file path -->
     <script src="anime-cursor.umd.min.js"></script>

Basic Usage

Initialize AnimeCursor:

new AnimeCursor({
    // Configuration area
});

In the configuration area, configure your AnimeCursor via cursors:

cursors: {
    // Cursor type declaration area
}

In the cursor type declaration area, declare your cursor types via cursors:

cursorTypeOne: {
    // Cursor parameter area
},
/* Note: Don't forget to add commas between two cursor types */
cursorTypeTwo: {
    // Cursor parameter area
}

In the corresponding cursor type's cursor parameter area, configure the cursor parameters by referring to Configuration: Parameter Options:

The configuration structure of an AnimeCursor containing two cursor types should look like this:

new AnimeCursor({
    cursors: {
        cursorTypeOne: {
            // settings
        },
        cursorTypeTwo: {
            // settings
        }
    }
});

Example

A minimal runnable example:

new AnimeCursor({
    cursors: {
        pointer: {
            tags: ['a','button']
            size: [32,32],
            image: 'cursor_pointer.png',
            default: false
        }
    }
});

In simple terms, in this code we set up a cursor type called pointer. This cursor has dimensions of 32 × 32 pixels, uses the image cursor_pointer.png, and it will display when cursor hovers an 'a' element or a 'button' element.

Please note that if cursor_pointer.png is a sprite sheet, in this example the pointer cursor will still only appear as a static cursor because it lacks some necessary parameter settings for sprite sheet animated cursors. The specific reasons will be mentioned next.

Here is a richer and more practical example containing four cursor types:

new AnimeCursor({
    cursors: {
        default: {
            size: [32,32],
            image: 'https://example.com/cursor_default.gif',
            pixel: true,
            default: true
        },
        pointer: {
            tags: ['a','button'],
            size: [32,36],
            image: 'https://example.com/cursor_pointer.png',
            frames: 3,
            duration: 0.3,
            pingpong: true,
            offset: [10,4],
            pixel: true
        },
        text: {
            tags: ['p','h1','h2','h3','h4','span','td','th','pre','code','footer'],
            size: [32,32],
            image: 'https://example.com/cursor_text.png',
            offset: [10,16],
            pixel: true
        },
        special: {
            size: [48,32],
            image: 'https://example.com/cursor_special.png',
            frames: 24,
            duration: 2,
            offset: [24,16],
            pixel: true
        }
    }
});

The example code includes four cursor types: default, pointer, text and special.

Among these three cursor types, only pointer has frames and duration set. This is because pointer is a PNG sprite sheet animated cursor, and in AnimeCursor, frames and duration are required parameters for sprite sheet animated cursors. If either of these parameters is missing, that cursor type will be rendered as static. Although default cursor doesn't have frames and duration set, its image points to a GIF animation, so the default cursor will be presented with the GIF's animation (the animation effect is determined by the GIF itself).

You may have noticed: aside from the default cursor, the special cursor also has no tags set. Therefore, it can only be triggered on elements that have data-cursor="special" manually added to them.

This is just a brief explanation of AnimeCursor configuration. For more detailed initialization configuration, please refer to the Configuration page.