Repository navigation
Releases
v2.2.0
[New Feature] Added the once cursor option
- Added per-cursor option
once(defaultfalse). When enabled, the cursor animation plays only once instead of looping. - With normal playback, the animation stops on the last frame. With
pingpong: true, it plays forward and backward once, then stops on the first frame.
v2.1.3
[New Feature] Enhanced debug mode: crosshair helper + hover transparent info panel
- Added a mouse‑following crosshair (horizontal and vertical red lines) in debug mode, helping users visually calibrate cursor hot spot offset.
- The top‑left debug information panel now becomes semi‑transparent when hovered, allowing users to see the content underneath.
- The crosshair is properly created or cleaned up during
disable/enable/refresh/destroy, fully compatible with existing debug behavior.
v2.1.2
[Bug Fix] Static cursor now has a non-looping one-frame animation to prevent being overridden by default cursor animation
- Previously, static cursors (without
frames/duration) could still inherit the default cursor's animation due to CSS cascade, causing visual glitches. - Now, static cursors are given a one-frame animation that plays once and then stops (
forwardsfill mode), ensuring they correctly override the default cursor without causing continuous repaints. - This approach eliminates the performance overhead of an infinite loop animation.
v2.1.1
[Bug Fix] Improved disable() / enable() to avoid affecting other animations
- Previously,
disable()added a global CSS rulebody.animecursor-disabled * { cursor: auto !important; animation: none !important; }, which would accidentally disable all animations on the page. - Now,
disable()removes AnimeCursor's injected style sheet and debug elements, restoring native cursors without touching any other animations. enable()re-injects the style sheet and rebuilds the debug overlay, fully restoring AnimeCursor functionality.- This change makes the API safe to use in any context without side effects.
v2.1.0
-
[New Feature] Combine animations (
combineAnimations)- Added global option
combineAnimations(defaultfalse). When enabled, AnimeCursor automatically looks for elements with thedata-ac-animationattribute and merges the user-defined animation(s) with the cursor animation, allowing both to run simultaneously. This solves the issue where an element's own animation would override the cursor animation. - Usage: set
combineAnimations: trueand adddata-ac-animation="yourAnimationString"to the element.
- Added global option
-
[Improvement] Default cursor is now optional
- It is no longer required to have a default cursor. If none is set, elements that do not match any custom cursor will use the system cursor, offering greater flexibility.
v2.0.1
v2.0.0
【Major Update】New Architecture: Native CSS Cursor Animation
Starting from v2.0.0, AnimeCursor has been completely refactored. Instead of using a simulated cursor element (div), it now leverages the browser's native CSS cursor (cursor: url()) combined with CSS keyframe animations to achieve frame-by-frame effects. This change brings the following benefits:
- Significant Performance Improvement: No need for JavaScript to track mouse movement (except in debug mode); cursor following is handled entirely by the browser.
- Precise Positioning: The hotspot offset of the native cursor is accurately calculated by the browser, eliminating the offset errors that occurred with simulated cursors.
【New Feature】Automatic Frame Sequence Recognition
Users only need to provide the filename of the first frame image. AnimeCursor will automatically recognize the numeric sequence and generate the URLs for subsequent frames. Supported formats include:
- 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 …
- If no number is present, _%d will be appended automatically.
This feature greatly simplifies the configuration process for multi-frame cursors.
【Removed】Deprecated Configuration Options
- **`size`**: Cursor size is now determined by the actual dimensions of the image and no longer requires configuration.
- **`scale`**: Scaling is no longer handled by the library; please pre-adjust the image size.
- **`pixel`**: Pixelated rendering is now determined by the image itself; the library no longer intervenes.
- **`displayOnLoad`**: No longer needed, as the native cursor is always visible.
- **Sprite Sheet Mode**: No longer supported. Please use individual frame images. To migrate from a sprite sheet, you can use auxiliary tools or manually slice the images.
【Change】Debug Mode Modification
Debug mode now displays the current cursor type and coordinates in a fixed floating panel for easier development and debugging. Note that debug mode enables mousemove listener (only in debug mode) and does not affect the production environment.
【Change】Global Toggle disable() / enable()
Temporarily disables all custom cursors and restores native cursor behavior by adding the animecursor-disabled class to the <body>.
【Migration Guide】
Migrating from v1 to v2 requires configuration changes:
- Remove all
size,scale, andpixelconfigurations. - Split the sprite sheet into individual frame images and store them following a consistent naming convention.
- Point
imageto the first frame image, and setframesandduration(as a number or array). - Ensure that the image size has been scaled to the final display size.