Installation

1. Prepare Cursor Images

   AnimeCursor v2 uses independent frame images (not sprite sheets). You need to prepare a set of images for each animated cursor, with filenames that follow a numeric pattern. The first frame must contain a number (e.g., cursor_01.png). AnimeCursor will automatically detect the pattern and generate URLs for subsequent frames.

   Supported naming patterns:

   • cursor001.png → cursor002.png → cursor003.png
   • cursor_001.png → cursor_002.png → cursor_003.png
   • cursor(01).png → cursor(02).png → cursor(03).png
   • cursor[1].png → cursor[2].png → cursor[3].png
   • cursor_1.png → cursor_2.png → cursor_3.png (no padding)

   If no number is found, AnimeCursor will add _%d (e.g., cursor.png → cursor_1.png). All frames must be the same size; the actual cursor size is the natural image size – scale images beforehand if needed.

   Static cursors (single image) are also supported – just omit frames and duration.

2. Deploy AnimeCursor

   • CDN

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

   • npm

     npm i anime-cursor

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

   • Host Yourself

     <script src="anime-cursor.umd.min.js"></script>

Basic Usage

Initialize AnimeCursor:

new AnimeCursor({
    // configuration
});

Define your cursors inside cursors:

cursors: {
    cursorTypeOne: { /* parameters */ },
    cursorTypeTwo: { /* parameters */ }
}

Each cursor must have an image (first frame) and, if animated, frames and duration. Use tags to automatically apply the cursor to specific HTML elements, or manually add data-cursor="cursorType" to elements.

Combining Animations

If you have elements that already use CSS animations (e.g., animation: spin 2s infinite), those animations can conflict with AnimeCursor's cursor animations. To let both play simultaneously, enable the combineAnimations option:

new AnimeCursor({
    combineAnimations: true,
    cursors: { ... }
});

Then, add the data-ac-animation attribute to the element, with the value being your own animation definition(s). AnimeCursor will automatically merge the cursor animation with yours:

<button data-ac-animation="mySpin 2s linear infinite">Click Me</button>

Multiple animations can be listed, separated by commas.

Example

A minimal working example:

new AnimeCursor({
    cursors: {
        default: {
            image: '/cursor/default.png',
            default: true
        },
        pointer: {
            tags: ['a', 'button'],
            image: '/cursor/pointer_001.png',
            frames: 4,
            duration: 0.4,
            offset: [15, 25],
            pingpong: true
        },
        text: {
            tags: ['p', 'h1', 'h2', 'span'],
            image: '/cursor/text.png'  // static cursor
        }
    }
});

In this example:

• default cursor (static) is used when no other cursor matches.
• pointer is an animated cursor with 4 frames (uniform timing) and ping‑pong loop.
• text is a static cursor applied to text elements.

You can also use array‑based variable speed:

pointer: {
    tags: ['a', 'button'],
    image: '/cursor/pointer_01.png',
    frames: [2, 3],      // first 2 frames, then 3 frames
    duration: [0.2, 1.0], // total 1.2s
    offset: [15, 25]
}

Upgrading from v1

AnimeCursor v2 is a complete rewrite. If you're upgrading from v1, please note:

• Sprite sheets and GIF are no longer supported – you must split your sprite sheet into individual frame images (sprites). A helper script may be provided separately. Also, GIF are nolonger supported, due to native cursor doesn't supports GIF (it will work but no animation will be played).
• Removed options: size, scale, pixel, zindex, displayOnLoad. Cursor size is now determined by the image itself.
• New options: fallbackCursor, excludeSelectors (global), combineAnimations, and per‑cursor fallback.
• Default cursor is optional – you can omit it; elements without a matching cursor will use the system cursor.
• Animation timing now supports arrays for variable speed.

For most projects, migration is straightforward: replace sprite sheets with numbered frames, remove deprecated options, and test.