Haha, cool cursor go brrrr...
Table of Content
What is this?
BetterPointer is a JS/TS package that simulates adaptive precision on a webpage with the intention of making buttons and other elements on a website/webapp easier to interact with.
It was largely inspired by the ipadOS cursor, but is implemented in such a way that allows for greater visual and behavioral customization.
You can try the pointer out at: https://lemonorangewastaken.github.io/BetterPointer/
Getting Started
This section will cover what you need to setup and start using your cursor.
Installation
Note: if you are using JS without NPM, a cdn accessible
min.jsfile is not yet avaiable, but should hopefully be soon.
This package is available on NPM, and currently supports TS and JS. To install, setup an npm project by running:
npm init -y
Then, install the package by running
npm i betterpointer
Please note: this package only works with frontend JS/TS, and will not work on NodeJS/TS. If you need instructions on how to setup npm libraries for frontend JS, please read this article.
Setup
To setup the cursor in your project, create an empty div under the body tag of your HTML file, and give it a unique id. Ex:<body>
<div id="some-unique-id"></div>
<!-- rest of your document... -->
</body>
Make sure that there are no styles applied to this div, either in the inline HTML or in a linked CSS sheet.
In your JS/TS file, import the package:
import cursor from "betterCursor";
Then, create an instance of the cursor. This is what will be used to control your cursor, such as toggling light and dark mode.
const myCursor = new cursor("some-unique-id");
You may also pass in a configuration object, like so:
const config = {
size : "50px",
mass : 125
};
const myCursor = new cursor("some-unique-id", config);
Configurable parameters:
| Key | Default | Units | Descritpion |
|---|---|---|---|
| size | "24px" | - | The default size of the cursor. |
| mass | 75 | - | How "heavy" the cursor feels. |
| trackingPeriod | 50 | ms | The period in which the cursor will check for elements to snap on to. |
Usage
This section will cover how to utilize your cursor to its full potential.
Cursor controls
These are functions that you can use to control the cursor's appearance and behavior.
Setting the cursor's dark/light appearance
If your site contains a toggleable dark theme or you need to forcibly change the light/dark appearance of your cursor, you may use these two functions to do so:
myCursor.setDark(); // make the cursor visible in dark theme
myCursor.setLight(); // make the cursor visible in light theme
Note: setDark() will set the cursor to a translucent white color and is meant to be used in a dark themed environment. It does not make the cursor itself dark! The same logic applied to setLight() as well.
Forcibly morphing/snapping the cursor
Doing this is not reccomended, as it is still in development and can act buggy. But if, for whatever reason, you need to morph/snap the cursor to an element, you may use this command to do so:
// morph the cursor into text mode,
// and apply this effect in reference of myElmnt
setShape("text", myElmnt, false, 15);
Here's what each of the parameter means (in order):
| Name | Type | Optional | Default | Descritpion |
|---|---|---|---|---|
| shape | String |
|
- | Shape that the cursor should morph to |
| elmnt | HTMLElement |
|
currentHoveringElmnt | The reference element (to get parameters such as size and line height from) |
| hideCursor | Boolean |
|
false | Whether or not to hide the cursor |
| snapCoef | Number |
|
10 | The larger the number is, the more the element will stick to the cursor. |
All the shapes that are available (if the shape doesn't match any in this table, the cursor will just return to normal):
| Shape | Description |
|---|---|
| Text | Morph your cursor into a text selection shape, with height matching the line height |
| input | Similar to the text selection, except there will be a bit of Y snapping in the text input box |
| button | Complete snap onto an element in the X and Y direction |
Element Settings
Your cursor will only morph/snap onto elements you specified. So if you have a button but didn't specify for the cursor to snap onto it, it will be ignored as a normal element.
BetterPointer uses custom HTML attributes to identify target elements. Some examples are provided below:
<!-- Morph the cursor into text selection mode -->
<p snaptext> Lorem ipsum dolor sit amet... </p>
<!-- Snap the cursor onto a button -->
<button snapbutton> Click Me! </button>
Some of attributes available to configure cursor snap target:
| Attributes | Snap To Elmnt | Description |
|---|---|---|
| snaptext |
|
morphs the cursor into the text's shape. |
| snapinput |
|
snaps the cursor into the input box. |
| snapbutton |
|
snaps the cursor to the shape of the button (works on different elements too). |
| bigsnapbutton |
|
Same as snapbutton, but hides the cursor and is more sticky. |
Some of the attributes available to configure cursor behavior:
| Attributes | Example | Description |
|---|---|---|
| growth | "10px" | Enlarges the cursor by specified amount (Ex: 10px). |
Note: in snapbutton and bigsnapbutton mode, the cursor will morph to the element's bounding box width, height, and corner radius. It is advised to add some padding and corner radius to your elements for an optimal snapping effect.
Known issues
Here are some known issues about the library so far:
- Safari absolutely refuses to work with the web (as well as Internet Explorer).
- Does not work well with transitioning elements
- Random errors in the console sometimes
- Immense lag on opening up dev tools
- Poor behavior with mouse on demo page
Troubleshooting
If your cursor does not show up, please check if there is any elements overlaid on top of it that has a z-index over 999999. If there is some other errors, please file an issue report here, or make a pull request.
Contributing
You can't yet, but if you would like to work on it for some reason, please contact me at [email protected]
License
BetterPointer is licensed under the GPL-3.0 license, please respect it.
32 Dec 25, 2022
6 Aug 7, 2022
155 Dec 29, 2022
10 Nov 15, 2022
14 Apr 22, 2022
19 Dec 31, 2022
7 Oct 4, 2022
3 May 18, 2022
4 May 3, 2022
14 Jan 3, 2023