ipad-cursor
v0.5.2TypeScript
Mouse effect of iPad in browser that can be used in any framework
0/weekUpdated 2 years agoMITUnpacked: 96.7 KB
Published by CatsJuice
npm install ipad-cursor
ipad-curosr
Mouse effect hacking of iPad in browser that can be used in any frameworks
---
Install
- NPM
``bash`
npm install ipad-cursor --save
- CDN
Only support ESM module`
html
Block
text
`
See cursor.oooo.so for more details.
Usage
$3
Apply data-cursor attribute to the element you want to add the effect.data-cursor="text"
- : text cursordata-cursor="block"
- : block cursor
`html`
Text Cursor
Block Cursor
After your dom loaded, call initCursor to start the effect. You may need to call updateCursor() when dom updated.
`js
import { initCursor } from 'ipad-cursor'
initCursor()
`
> ⚠️ Notice: As so far, you need to manage when to updateCursor yourself. Make sure to call updateCursor after dom updated.
> In the future, there maybe a better way to handle this, see Roadmap for more details.
$3
You can customize the style of the cursor by Config, config can be passed to initCursor method, or use updateConfig method to update config. Every type can be configured separately.
`ts
import { initCursor, updateConfig } from 'ipad-cursor'
import type { IpadCursorConfig, IpadCursorStyle } from 'ipad-cursor'
const normalStyle: IpadCursorStyle = { background: 'red' }
const textStyle: IpadCursorStyle = { background: 'blue' }
const blockStyle: IpadCursorStyle = { background: 'green' }
const config: IpadCursorConfig = {
normalStyle,
textStyle,
blockStyle,
};
initCursor(config)
`
Sometimes, you may want to customize the style of the cursor for a specific element, you can use data-cursor-style attribute to do this.
The value of data-cursor-style attribute is a string, split by ;, and each part is a style, split by :. For example, background:red;color:blue.
It is recommended to use customCursorStyle method to create style string.
For example, customize the style for a circle element (Like avatar).
`html
data-cursor="block"
data-cursor-style="radius: 50%"
style="width: 50px; height: 50px; border-radius: 50%"
/>
`
See Style for full style list.
$3
- Vue.js
- hooks
You can use useCursor hook to call updateCursor() automatically on mounted and unmounted.`
ts`
- directive
Register plugin globally
`ts
// src/main.ts
import { ipadCursorPlugin } from "ipad-cursor/vue"
app.use(ipadCursorPlugin, {
// global configurations
blockStyle: { radius: "auto" }
})
`
Use in component
`html`
- React
See App.tsx
- Hexo
See @zqqcee's Blog
Principle
When initCursor called, it will remove default cursor, and generate a fake cursor use div element. Then listen mousemove event, and move the fake cursor to the mouse position.
After init finished, it will call updateCursor method, scan element with data-cursor attribute, detect the cursor type, and add event listener to the element.
When mouse enter the element, apply styles.
API
$3
> see Config for more details.
Init cursor, remove default cursor, and generate a fake cursor use div element. Then listen mousemove event, and move the fake cursor to the mouse position.
$3
Scan element to observe hover event, and apply styles, as well as remove unused element's event listener.
$3
Remove fake cursor, and remove all event listener, recover default cursor.
$3
Update config, see Config for more details.
$3
Create style string that can be used as data-cursor-style
attribute.
This method is used for better type hinting.$3
Reset cursor to default style.Config
It is recommended to see index.d.ts in the npm package.
| Name | Type | Default | Description | required |
| ------------------------------------------------- | ----------------- | ------------------- | -------------------------------------------------------------------------------------- | -------- |
|
adsorptionStrength | number | 0.2 | The strength of adsorption effect, number between 0 and 30 | No |
| className | string | 'ipad-cursor' | The class name of fake cursor | No |
| blockPadding | number | auto | The padding of cursor when hover on block, set to auto will calculate automatic | No |
| enableAutoTextCursor(v0.2.0+) | boolean | false | Auto detect text cursor, see #12 | No |
| enableLighting(v0.3.0+) | boolean | false | Add a lighting effect to block #14 | No |
| enableMouseDownEffect(v0.4.3+, Experimental) | boolean | false | Add a effect when mouse down, customize style by config mouseDownStyle | No |
| enableAutoUpdateCursor(v0.5.0+) | boolean | false | Auto update cursor when dom updated | No |
| normalStyle | IpadCursorStyle | see Style | The style of normal cursor, see Style | No |
| textStyle | IpadCursorStyle | see Style | The style of text cursor, see Style | No |
| blockStyle | IpadCursorStyle | see Style | The style of block cursor, see Style | No |
| mouseDownStyle(v0.4.3+, Experimental) | IpadCursorStyle | see Style | The style of cursor when mouse is pressed, see Style | No |Style
| Name | Type | Description | example |
| ------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
|
width | MaybeSize | The width of cursor | '10px', 10, '10' |
| height | MaybeSize | The height of cursor | '10px', 10, '10' |
| radius | MaybeSize \| 'auto' | The border radius of cursor, if set to auto for blockStyle, it will be calculated by dom's css border-radius and config.blockPadding. | '10px', 10, '10', 'auto' |
| background | string | The background color of cursor | '#fff', 'red', 'rgba(0,0,0)' |
| border | string | The css border property of cursor | '1px solid black' |
| zIndex | number | The z-index of cursor | 1 |
| scale | number | The scale of cursor | 1.05 |
| backdropBlur | MaybeSize | The backdrop-filter blur of cursor | '10px', 10, '10' |
| backdropSaturate | string | The backdrop-filter saturate of cursor | 180% |
| durationBase | MaybeDuration | Transition duration of basic properties like width, height, radius, border, background-color, if unit if not specified, ms will be used | '1000', 1000, 200ms, 0.23s |
| durationPosition | MaybeDuration | Transition duration of position properties like top, left, if unit if not specified, ms will be used | '1000', 1000, 200ms, 0.23s |
| durationBackdropFilter | MaybeDuration | Transition duration of backdrop-filter property, if unit if not specified, ms will be used | '1000', 1000, 200ms, 0.23s |$3
See
getDefaultConfig method in index.ts for more details.
Roadmap
- [x] Add Chinese document
- [x] API Docs
- [ ] More examples
- [x] Auto detect dom update, and call
updateCursor` automatically- Maybe use MutationObserver