Configuration
cursors is the core configuration option in AnimeCursor. Each key represents a cursor type, corresponding to a CSS class
(cursor-${type}, automatically generated by AnimeCursor). You have complete freedom to name the cursor types; any valid JavaScript identifier will work without affecting the result.
cursors: {
default: { ... },
pointer: { ... },
text: { ... },
cursorForFun: { ... }
}To make these cursors actually work, you also need to configure basic parameters for them, telling AnimeCursor how you want these cursors to be presented.
The table below lists all parameter options reserved by AnimeCursor for cursors, which can be used for quick reference. For a more detailed introduction to each parameter, please see the sections below.
| Option | Type | Required | Description | Behavior When Empty |
|---|---|---|---|---|
| size | [number, number] | ✅ | Cursor dimensions [width, height] (pixels) | Error |
| image | string | ✅ | Path to cursor image | Error |
| tags | string[ ] | Target HTML tags | AnimeCursor will only switch to this cursor when hover an element that has data-cursor setted by user manually | |
| default | boolean | ⚠️ | Whether the cursor is the default cursor ⚠️ Only one default cursor can be set | Same as setting to false |
| frames | number | Number of frames for sprite sheet animation | Cursor will not be animated as a sprite sheet | |
| duration | number | Loop duration for sprite sheet animation (seconds) | Cursor will not be animated as a sprite sheet | |
| pingpong | boolean | Whether sprite sheet animation uses ping-pong loop | Sprite sheet animation loops normally | |
| offset | [number, number] | Cursor offset [right, down] (pixels) | Cursor pointer position defaults to top-left corner | |
| scale | [number, number] | Cursor scaling factor [horizontal, vertical] | Cursor maintains size as set | |
| pixel | boolean | Whether to enable pixelated rendering | Original pixel art edges are smoothed | |
| zindex | number | Set z-index specifically for this cursor (at <body> level) | Defaults to maximum z-index minus 1 |
size is a required parameter for cursors. It indicates the dimensions (unit: pixels) of the cursor this parameter belongs to.
Format:
size: [sizeX , sizeY]Example:
size: [32 , 32]The example above means: The cursor this parameter belongs to has dimensions of 32px × 32px. If this cursor is a sprite sheet animated cursor, the frame size of the sprite sheet is also 32px × 32px.
image is a required parameter for cursors. It indicates the image path for the cursor this parameter belongs to.
Format:
image: 'path-to-your-image';Example:
// Can be a relative path
image: '/image/cursor/cursor-image.png';// Or an absolute path
image: 'https://example.com/image/cursor/cursor-image.png';The two examples above mean: The image path for the cursor this parameter belongs to is /image/cursor/cursor-image.png (first example) or https://example.com/image/cursor/cursor-image.png (second example).
AnimeCursor recommends using absolute paths to set cursor images. If the website has a multi-layered page structure, using relative paths may cause AnimeCursor's image paths to mismatch, an issue that can be avoided by using absolute paths.
tags is an optional parameter in the cursor configuration. It specifies on which DOM elements the cursor should switch to the associated cursor style when the mouse pointer hovers over them. It works as follows: During initialization or refresh, AnimeCursor will automatically add the cursor's corresponding data-cursor attribute to the elements specified in tags (unless an element already has a data-cursor attribute). When the cursor moves over an element that has a data-cursor attribute, AnimeCursor automatically recognizes the cursor type associated with that element and switches to that cursor.
When tags is not set, AnimeCursor will not add its corresponding data-cursor attribute to any elements in the HTML. If you need to trigger this cursor, you must manually add the data-cursor attribute to the triggering element(s).
Format:
tags['tag-1' , 'tag-2' , 'tag-3']Example:
tags['a' , 'button' , 'span']The example above means: AnimeCursor will switch to this cursor when the mouse pointer hovers over a elements, button elements, and span elements.
Assuming this tags parameter belongs to the pointer cursor, then when the mouse pointer hovers over any of the following elements:
<a href="/">A element</a>
<button type="button">BUTTON element</button>
<span>SPAN element</span>
<!-- element that has a data-cursor="pointer" setted by user -->
<!-- (no matter what tag the element is) -->
<div data-cursor="pointer"></div>AnimeCursor will automatically switch to the pointer cursor.
A cursor with its default parameter set to true will automatically be applied by AnimeCursor to all undeclared situations.
If the cursor is sprite animation cursor, pleast make sure that image links to the sprite sheet, not one of the frames or a folder.
Element tags set within tags are globally non-repeatable.
If an element tag has already been declared in one cursor, it cannot be declared again in other cursors. That is, different cursors cannot share the same target element tags.
default is an optional parameter for cursors. When set to true, it indicates that the cursor this parameter belongs to is the default cursor.
When this parameter is not set, the behavior is the same as setting it to false; AnimeCursor will not treat this cursor as the default.
AnimeCursor can set at most one cursor as the default cursor. If more than one cursor is set as default, AnimeCursor will throw an error.
Format:
default: true-or-false;Example:
default: true;The example above means: The cursor this parameter belongs to is the default cursor.
The default cursor does not need the tags parameter. AnimeCursor recommends that the default cursor should not set the tags parameter, as it does not affect the switching logic of the default cursor. However, setting this parameter for the default cursor may cause target conflicts with other cursors.
frames is an optional parameter for cursors, but it is required for sprite sheet animated cursors. It indicates the number of frames contained in the sprite sheet animation for the cursor this parameter belongs to (within one loop).
Format:
frames: frames-count;Example:
frames: 6;The example above means: The sprite sheet animation for the cursor this parameter belongs to has 6 frames per loop.
duration is an optional parameter for cursors, but it is required for sprite sheet animated cursors. It indicates the duration of the sprite sheet animation for the cursor this parameter belongs to (per loop, unit: seconds).
Format:
duration: loop-length;Example:
duration: 2;The example above means: The duration of one loop of the sprite sheet animation for the cursor this parameter belongs to is 2 seconds.
Only when both the frames and duration parameters are configured legally will AnimeCursor treat the cursor as a sprite sheet animated cursor. If either parameter is missing or configured illegally, AnimeCursor will throw an error.
pingpong is an optional parameter for cursors. It indicates whether the ping-pong loop is enabled for the cursor this parameter belongs to.
When this parameter is not set, the behavior is the same as setting it to false. If the cursor is a sprite sheet animated cursor, the animation will loop from the beginning after finishing.
GIF animation playback is controlled by the image itself. AnimeCursor does not modify GIFs, so setting this option for a GIF cursor is ineffective.
Format:
pingpong: true-or-false;Example:
pingpong: true;The example above means: If the cursor this parameter belongs to is a sprite sheet animated cursor, the ping-pong loop is enabled.
offset is an optional parameter for cursors. It indicates the pointer offset for the cursor this parameter belongs to (unit: pixels).
Format:
offset: [offsetX , offsetY]Example:
offset: [5 , 10]The example above means: The pointer offset for the cursor this parameter belongs to is 5px horizontally and 10px vertically.
scale is an optional parameter for cursors. It indicates the scaling factor for the cursor this parameter belongs to.
Format:
scale: [scaleX , scaleY]Example:
scale: [2 , 0.5]The example above means: The cursor this parameter belongs to is scaled by a factor of 2 horizontally and 0.5 vertically.
pixel is an optional parameter for cursors. It indicates whether pixelated rendering is enabled for the cursor this parameter belongs to.
When this parameter is not set, the behavior is the same as setting it to false; the cursor will use the browser's default rendering method.
For pixel art cursors, using original-sized pixel art, enabling pixel, and setting a scale can save file size and reduce loading time.
Format:
pixel: true-or-false;Example:
pixel: true;The example above means: The image for the cursor this parameter belongs to will be rendered with pixelated filtering.
zindex is an optional parameter for cursors. It sets the z-index specifically for the cursor this parameter belongs to.
Format:
zindex: number;Example:
zindex: 10;The example above means: The z-index for the cursor this parameter belongs to is specifically set to 10.
For situations where the cursor needs to be occluded by certain elements, note when setting this option: The value of z-index is only meaningful within the same stacking context, and AnimeCursor's cursor element is a direct child of <body>.
Adding a configuration option or API to determine the injection location of the cursor element might be possible, but this may not align with the direction of AnimeCursor's development, so injection positioning functionality is highly unlikely to be added.
In addition to the cursors themselves, AnimeCursor provides a few global options at the same level as cursors:
| Option | Type | Default | Description |
|---|---|---|---|
| debug | boolean | false | Enable debug overlay |
| displayOnLoad | boolean | false | Sets whether the cursor should be displayed before mouse movement is detected |
| enableTouch | boolean | false | Whether to enable on touchscreen devices |
A very important option. Set to true to enable debug mode.
Debug mode displays the real mouse pointer position and the current cursor type, helping to correct alignment offsets or troubleshoot other errors.
Sets whether the cursor should be displayed before mouse movement is detected. If enabled, the cursor will remain top-left until mouse movement (within the viewport) is detected.
After the cursor DOM is inserted during initialization, its initial position is at the top-left corner. It only corrects to the mouse position when the mouse moves within the viewport, which can be visually jarring. Starting to display the cursor only after the mouse moves inside the viewport is a better approach, so displayOnLoad generally does not need to be set.
Used to enable animated cursors on mobile touchscreen devices.
AnimeCursor automatically detects mobile touchscreen devices (like phones, tablets) and disables animated cursors on them by default. If you want to display animated cursors on these devices, add enableTouch: true.
Since global options are at the same level as cursor types, pay attention to the code format when setting global parameters:
new AnimeCursor({
debug: true, // At the same level as cursors, correct format
enableTouch: false, // At the same level as cursors, correct format
cursors: {
default: {
size: [32,32],
image: 'i/cursor/cursor_default.gif',
pixel: true,
default: true
},
}
});An AnimeCursor initialization with global options set should look like the example above.
new AnimeCursor({
cursors: {
debug: true, // Wrapped inside cursors, incorrect location
default: {
size: [32,32],
image: 'i/cursor/cursor_default.gif',
pixel: true,
default: true,
enableTouch: false // Wrapped inside cursor settings, incorrect location
},
}
});The example above is an incorrect demonstration. Note the location of debug and enableTouch in the code and the comment text.