@tochiresources/cursors v1.1.3

Use custom cursors in your HTML, CSS & JavaScript application (Browser & NodeJs).

• Simple and easy to use.
• Can also be used in your own application.
• Primarily uses tochiResources cursors, use your own cursors instead if necessary.
• Works in both NodeJs and Browser contexts (read more below).

Demo

See live demo here

Install

Method 1 Import directly into your .css file (recommended): 1. Download the cursors at Releases and then add this to your main .css file:

/* Variables */
:root {
    /* navigate to cursors */
    --cursor-default: url("./web-friendly/32x32/pointer.png") 3 3, auto;
    --cursor-pointer: url("./web-friendly/32x32/link.png") 5 2, auto;
    --cursor-text: url("./web-friendly/32x32/beam.png") 16 16, auto;
}
/* Semantic tags */
/* default */ body, [type], p, label, span, h1, h2, h3, h4, h5, h6, body:disabled, [type]:disabled, header:disabled, nav:disabled, div:disabled, main:disabled, section:disabled, article:disabled, aside:disabled, footer:disabled, details:disabled, figure:disabled, a:disabled, p:disabled, label:disabled, span:disabled, h1:disabled, h2:disabled, h3:disabled, h4:disabled, h5:disabled, h6:disabled, input[type="button"]:disabled, input[type="checkbox"]:disabled, input[type="reset"]:disabled, input[type="radio"]:disabled, input[type="range"]:disabled, input[type="submit"]:disabled, input:disabled, input[type="file"]:disabled, input[type="text"]:disabled, input[type="email"]:disabled, input[type="password"]:disabled, input[type="search"]:disabled, input[type="date"]:disabled, input[type="datetime-local"]:disabled, input[type="month"]:disabled, input[type="week"]:disabled, input[type="number"]:disabled, input[type="tel"]:disabled, input[type="time"]:disabled, input[type="url"]:disabled, button:disabled { cursor: var(--cursor-default) !important; }
/* pointer */ a, a:hover, input[type="button"], input[type="checkbox"], input[type="reset"], input[type="radio"], input[type="range"], input[type="submit"], button, button:hover { cursor: var(--cursor-pointer) !important; }
/* text */ input, input[type="file"], input[type="text"], input[type="email"], input[type="password"], input[type="search"], input[type="date"], input[type="datetime-local"], input[type="month"], input[type="week"], input[type="number"], input[type="tel"], input[type="time"], input[type="url"] { cursor: var(--cursor-text) !important; }

OR

Method 2 Import into a framework (like ReactJS) - remember to import it after your main .css imports 1. Download the cursors at Releases and then add this to your main .css file:

:root {
    /* navigate to cursors */
    --cursor-default: url("./web-friendly/32x32/pointer.png") 3 3, auto;
    --cursor-pointer: url("./web-friendly/32x32/link.png") 5 2, auto;
    --cursor-text: url("./web-friendly/32x32/beam.png") 16 16, auto;
}

2. Import into your framework index file:

npm i @tochiresources/cursors

import "@tochiresources/cursors/index.css";

OR

Method 3 Install using npm:

npm i @tochiresources/cursors

Examples (if installed with method 3)

JavaScript

const cursors = require('@tochiresources/cursors');

Use multiContext to enable multicontextual support eg. NodeJs and Browser contexts at the same time.

• Enabling this will prioritize Browser context.

cursors.multiContext(true);

(NodeJs) Apply once for all semantic and relevant elements with apply.

// simple
cursors.apply('./css/styles.css', './css');

// with more arguments
cursors.apply('./css/styles.css', './css', cursors.CursorSize.small, cursors.CursorColor.white, 200);

// with more arguments and custom cursors
cursors.applySelectors('./css/styles.css', './css', cursors.CursorSize.small, null, 200, { // color will be ignored when using custom options
  // override directory path
  // custom cursors should be placed in respective cursor size folder structure eg. 32x32/cursor.png, 64x64/cursor.png and 128x128/cursor.png
  cursorDir: "./test/cursors", // directory path containing cursor size folders (relative to the outputFolder if you change this)

  // override all available cursors
  default: { name: "pointer", offset: new CursorOffset(3, 3) },
  pointer: { name: "link", offset: new CursorOffset(5, 2) },
  text: { name: "beam", offset: new CursorOffset(16, 16) },
  progress: { name: "working", offset: new CursorOffset(3, 3) },
  wait: { name: "busy", offset: new CursorOffset(16, 16) },
  allScroll: { name: "move", offset: new CursorOffset(16, 16) },
  ewResize: { name: "horz", offset: new CursorOffset(16, 16) },
  nsResize: { name: "vert", offset: new CursorOffset(16, 16) },
  neswResize: { name: "dgn2", offset: new CursorOffset(16, 16) },
  nwseResize: { name: "dgn1", offset: new CursorOffset(16, 16) }
});

(Browser) Apply once for all semantic and relevant elements with applyWeb.

// simple
cursors.applyWeb('css/styles.css');

// with more arguments
cursors.applyWeb('css/styles.css', cursors.CursorSize.small, cursors.CursorColor.white, 200);

// with more arguments and custom cursors
cursors.applySelectorsWeb('css/styles.css', cursors.CursorSize.small, null, 200, { // color will be ignored when using custom options
  // override directory path
  // custom cursors should be placed in respective cursor size folder structure eg. 32x32/cursor.png, 64x64/cursor.png and 128x128/cursor.png
  cursorDir: "<your-root-folder>/bin/cursors", // directory path containing cursor size folders (absolute path is recommended)

  // override all available cursors
  default: { name: "pointer", offset: new CursorOffset(3, 3) },
  pointer: { name: "link", offset: new CursorOffset(5, 2) },
  ...
});

(NodeJs) Apply for custom individual elements with applySelectors.

// simple
cursors.applySelectors('./css/styles.css', './css', '#logo, .tab, .drop-zone');

// with more arguments
cursors.applySelectors('./css/styles.css', './css', '#logo, .tab, .drop-zone', cursors.CursorSize.small, cursors.CursorColor.white);

// with more arguments and custom cursors
cursors.applySelectors('./css/styles.css', './css', '#logo, .tab, .drop-zone', cursors.CursorSize.small, null, {
  cursorDir: "./bin/cursors",
  default: { name: "custom1", offset: new CursorOffset(3, 3), },
  pointer: { name: "custom2", offset: new CursorOffset(5, 3), },
  ...
});

(Browser) Apply for custom individual elements with applySelectorsWeb.

// simple
cursors.applySelectorsWeb('css/styles.css', '#logo, .tab, .drop-zone');

// with more arguments
cursors.applySelectorsWeb('css/styles.css', '#logo, .tab, .drop-zone', cursors.CursorSize.small, cursors.CursorColor.white);

// with more arguments and custom cursors)
cursors.applySelectorsWeb('css/styles.css', '#logo, .tab, .drop-zone', cursors.CursorSize.small, null, {
  cursorDir: "./bin/cursors",
  default: { name: "custom1", offset: new CursorOffset(3, 3), },
  pointer: { name: "custom2", offset: new CursorOffset(5, 3), },
  ...
});

In case you're confused about the difference between these methods:

• NodeJs
  • Use apply to automatically apply cursors on relevant semantic HTML tags and selectors.
  • Use applySelectors to apply cursors on specified selectors only.
• Browser
  • applyWeb same as NodeJs but only works in Browser context.
  • applySelectorsWeb same as NodeJs but only works in Browser context.

CSS (if installed with method 3)

You can apply cursor styles normally in your css file like:

.selectorClass div {
  cursor: text;
}

#selectorId a:hover {
  cursor: pointer;
}

and then the selector's cursor property will automatically be converted to a tochiResources cursor.

See supported cursor types down below or .

Please take a look at the API below for more details.

How it works (if installed with method 3)

When using apply(styleSheetUrl, size, color, delay, options):

1. Apply cursors on semantic HTML tags eg. button and a.
2. Find css file (styleSheetUrl) and read it's contents.
3. Find rules from css file contents with a cursor property and then obtain the selectors and cursor value.
4. Apply cursors on obtained data.

When using applySelectors(styleSheetUrl, selectors, size, color, options):

1. Find css file (styleSheetUrl) and read it's contents.
2. Find specified selectors from css file contents, check if the rules contains a cursor property and then obtain the selectors and cursor value.
3. Apply cursors on obtained data.

As you can see applySelectors skips semantic HTML tags and only focues on specified selectors.

• This approach allows a lightweight process and performs faster than using querySelector to apply cursors on HTML elements.
• The latter have been tested and performs extremely poorly.
• HTML elements' applied cursor property won't be overridden if changed through JavaScript because of the generated internal style tag (Browser) or the generated css file (NodeJs).

Output

• You can see how the css will look like by checking out .
• A .css file will be generated when using this in NodeJs context.
• A HTML <style> tag will be created/appended inside the <head> tag in Browser context.

Performance may become a concern if:

• Specified css file (styleSheetUrl) exceeds more than 2000 lines (not tested above this limit).

CssScanner

• This module uses to scan through specified css file (styleSheetUrl).

Notes

!IMPORTANT You don't need to specify a cursor property for semantic HTML tags. They will automatically be applied accordingly if you use apply or applyWeb. To include other HTML tags or elements they must require a valid class or id attribute and be referenced in your css file (styleSheetUrl).

!NOTE Dynamic sites:

May not work on dynamically added elements but that's when you can use the cursor.applySelectors('css/styles.css', selectors) function to apply cursors on specified elements.

Cursor sizes:

Most browsers won't support cursor sizes above small which is 32 x 32.

API

Methods

multiContext(value)

Set to true if your application is multicontextual eg. supports both NodeJs and Browser contexts at the same time

apply(styleSheetUrl, size, color, delay, options)

(NodeJs only) Automatically apply cursors on relevant semantic HTML tags and css selectors in a document.

applySelectors(styleSheetUrl, selectors, size, color, options)

(NodeJs only) Apply cursors on specified css selectors in a document.

applyWeb(styleSheetUrl, size, color, delay, options)

(Browser only) Automatically apply cursors on relevant semantic HTML tags and css selectors in a document.

applySelectorsWeb(styleSheetUrl, selectors, size, color, options)

(Browser only) Apply cursors on specified css selectors in a document.

Other arguments

options Arguments | Type | Default | Priority | Description --- | --- | --- | --- | --- cursorDir | string | './web-friendly' | optional | Directory path containing cursor size folders relative to your root directory (custom cursors should be placed in respective cursor size folder structure eg. 32x32/cursor.png, 64x64/cursor.png and 128x128/cursor.png) offset | CursorOffset | new CursorOffset(0, 0) | optional | Changes the cursor hotspot position using x and y from top right corner default | string | pointer | optional | Override cursor name pointer | string | link | optional | Override cursor name text | string | beam | optional | Override cursor name progress | string | working | optional | Override cursor name wait | string | busy | optional | Override cursor name allScroll | string | move | optional | Override cursor name ewResize | string | horz | optional | Override cursor name nsResize | string | vert | optional | Override cursor name neswResize | string | dgn2 | optional | Override cursor name nwseResize | string | dgn1 | optional | Override cursor name

Classes

CursorOffset

Changes the cursor hotspot position using x and y from top right corner.

Methods

• toString()

Constants

CursorName

common

• default: pointer
• pointer: link

• text: beam

  status

• progress: working

• wait: busy

  resizing & scrolling

• allScroll: move

• ewResize: horz
• nsResize: vert
• neswResize: dgn2
• nwseResize: dgn1

CursorSize

• small: 32x32
• medium: 64x64
• large: 128x128

CursorColor

• white
• gray