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).
[Method 1] Import directly into your .css file (recommended):
- 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
- 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;
}
- 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
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 withapply
.
// 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 withapplyWeb
.
// 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 withapplySelectors
.
// 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 withapplySelectorsWeb
.
// 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.
- Use
-
Browser
-
applyWeb
same as NodeJs but only works in Browser context. -
applySelectorsWeb
same as NodeJs but only works in Browser context.
-
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.
When using apply(styleSheetUrl, size, color, delay, options)
:
- Apply cursors on semantic HTML tags eg.
button
anda
. - Find css file (
styleSheetUrl
) and read it's contents. - Find rules from css file contents with a
cursor
property and then obtain the selectors and cursor value. - Apply cursors on obtained data.
When using applySelectors(styleSheetUrl, selectors, size, color, options)
:
- Find css file (
styleSheetUrl
) and read it's contents. - Find specified selectors from css file contents, check if the rules contains a
cursor
property and then obtain the selectors and cursor value. - 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
[!IMPORTANT] You don't need to specify a cursor property for semantic HTML tags. They will automatically be applied accordingly if you use
apply
orapplyWeb
. To include other HTML tags or elements they must require a validclass
orid
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 is32 x 32
.
multiContext(value)
Set to
true
if your application is multicontextual eg. supports both NodeJs and Browser contexts at the same time
Arguments | Type | Default | Priority | Description |
---|---|---|---|---|
value | boolean |
required | Should be used before apply , applyWeb , applySelectors and applySelectorsWeb
|
apply(styleSheetUrl, size, color, delay, options)
(NodeJs only)
Automatically apply cursors on relevant semantic HTML tags and css selectors in a document.
Arguments | Type | Default | Priority | Description |
---|---|---|---|---|
styleSheetUrl | string |
required | Url of the styleSheet that will be inspected relative to your root directory (accepts absolute path and web url) | |
outputFolder | string |
required | Directory path relative to your root directory for the generated css file tochiResources-cursors.css
|
|
size | string |
CursorSize.small |
optional | Choose a cursor size between small, medium and large (most browsers won't support cursor sizes above small) |
color | string |
CursorColor.white |
optional | Choose between white and gray (ignored when using custom options) |
delay | number |
200 |
optional | The delay for when cursors will be applied after all elements in the document has been rendered |
options | object |
see options below |
optional | Override default cursor options |
applySelectors(styleSheetUrl, selectors, size, color, options)
(NodeJs only)
Apply cursors on specified css selectors in a document.
Arguments | Type | Default | Priority | Description |
---|---|---|---|---|
styleSheetUrl | string |
required | Url of the styleSheet that will be inspected relative to your root directory (accepts absolute path and web url) | |
outputFolder | string |
required | Directory path relative to your root directory for the generated css file tochiResources-cursors.css
|
|
selectors | string |
required | Selectors that will be inspected | |
size | string |
CursorSize.small |
optional | Choose a cursor size between small, medium and large (most browsers won't support cursor sizes above small) |
color | string |
CursorColor.white |
optional | Choose between white and gray (ignored when using custom options) |
options | object |
see options below |
optional | Override default cursor options |
applyWeb(styleSheetUrl, size, color, delay, options)
(Browser only)
Automatically apply cursors on relevant semantic HTML tags and css selectors in a document.
Arguments | Type | Default | Priority | Description |
---|---|---|---|---|
styleSheetUrl | string |
required | Href value of the styleSheet that will be inspected (must match the href attribute value from your html/external file) | |
size | string |
CursorSize.small |
optional | Choose a cursor size between small, medium and large (most browsers won't support cursor sizes above small) |
color | string |
CursorColor.white |
optional | Choose between white and gray (ignored when using custom options) |
delay | number |
200 |
optional | The delay for when cursors will be applied after all elements in the document has been rendered |
options | object |
see options below |
optional | Override default cursor options |
applySelectorsWeb(styleSheetUrl, selectors, size, color, options)
(Browser only)
Apply cursors on specified css selectors in a document.
Arguments | Type | Default | Priority | Description |
---|---|---|---|---|
styleSheetUrl | string |
required | Href value of the styleSheet that will be inspected (must match the href attribute value from your html/external file) | |
selectors | string |
required | Selectors that will be inspected | |
size | string |
CursorSize.small |
optional | Choose a cursor size between small, medium and large (most browsers won't support cursor sizes above small) |
color | string |
CursorColor.white |
optional | Choose between white and gray (ignored when using custom options) |
options | object |
see options below |
optional | Override default cursor options |
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 |
CursorOffset
Changes the cursor hotspot position using x and y from top right corner.
Arguments | Type | Default | Priority | Description |
---|---|---|---|---|
x | number |
0 |
optional | x value in pixels |
y | number |
0 |
optional | y value in pixels |
Methods
- toString()
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