Repository navigation
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.