Template:ChangeCursor

Template documentation

Usage

This template changes the cursor picture for a given CSS selector or the entire page body. It uses the CustomCursor Lua module to generate the necessary CSS.

Parameters

• |image=: (Required) The filename of the cursor image uploaded to the wiki (e.g., "MyCursor.png", "Animated.gif").
• |selector=: (Optional) The CSS selector to apply the custom cursor to.

  Defaults to "body" (the entire page).

  Examples: "#myElementId", ".myClassName", "div.myClass a".

• |offsetX=: (Optional) The x-coordinate (horizontal offset) of the cursor's hotspot, measured from the left edge of the image. Defaults to 0 if not specified or if offsetY is also not specified.
• |offsetY=: (Optional) The y-coordinate (vertical offset) of the cursor's hotspot, measured from the top edge of the image. Defaults to 0 if not specified or if offsetX is also not specified.
• |fallback=: (Optional) The fallback cursor type if the image cannot be loaded or is not supported.

  Defaults to "auto".

  Common values: "default", "pointer", "move", "text", "wait", "help", "crosshair".

Examples

Change cursor for the whole page

{{ChangeCursor
|image = MyCoolCursor.png
}}

This will use "MyCoolCursor.png" (assuming it's uploaded) as the cursor for the entire page, with default hotspot (0,0) and "auto" fallback.

Change cursor for a specific element

An element with the ID "interactiveMap":

{{ChangeCursor
|image = MapPointer.cur
|selector = #interactiveMap
|offsetX = 5
|offsetY = 5
|fallback = pointer
}}

This applies "MapPointer.cur" to the element with ID "interactiveMap", setting the hotspot to 5 pixels from the left and 5 pixels from the top, with "pointer" as the fallback.

Change cursor for elements of a certain class

All elements with the class "clickable-icon":

{{ChangeCursor
|image = HandCursor.svg
|selector = .clickable-icon
|fallback = pointer
}}

Important Notes

• Image Upload: The image file specified in the |image= parameter must be uploaded to your wiki.
• Image Size: Cursor images should ideally be small. The recommended standard size is 32x32 pixels. While some browsers might support up to 128x128 pixels, larger images may be ignored or cause performance issues.
• Image Formats: Supported image formats typically include:
  • .png (recommended for static cursors with transparency)
  • .gif (for animated cursors, though browser support/performance can vary)
  • .cur (standard cursor format)
  • .svg (scalable vector graphics, good for sharp cursors at different resolutions)
• Browser Compatibility: Custom cursors are widely supported, but behavior with very large images or uncommon formats can vary between browsers. Always test on your target browsers.
• Hotspot Coordinates: If you provide |offsetX= or |offsetY=, it's best to provide both. These define the exact "tip" of your cursor image.
• Performance: Using many different custom cursors or very large/animated cursors excessively might impact page performance. Use judiciously.
• Caching: After applying the template, you might need to clear your browser cache or perform a hard refresh (Ctrl+F5 or Ctrl+Shift+R) to see the new cursor. Wiki server-side caching might also delay appearance.