catsjuice / ipad-cursor

● Mouse effect of iPad in browser that can be used in any framework

ipad-curosr

Mouse effect hacking of iPad in browser that can be used in any frameworks

---

Install

• NPM

  npm install ipad-cursor --save

• CDN

  Only support ESM module

  <div data-cursor="block">Block</div>
  <div data-cursor="text">text</div>
  
  <script type="module">
    import cursor from "https://unpkg.com/ipad-cursor@latest"
    cursor.initCursor()
  </script>

  See cursor.oooo.so for more details.

Usage

Basic usage

Apply data-cursor attribute to the element you want to add the effect.

• data-cursor="text": text cursor
• data-cursor="block": block cursor

<div data-cursor="text">Text Cursor</div>
<div data-cursor="block">Block Cursor</div>

After your dom loaded, call initCursor to start the effect. You may need to call updateCursor() when dom updated.

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.

Custom Style

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.

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).

<div 
  data-cursor="block" 
  data-cursor-style="radius: 50%" 
  style="width: 50px; height: 50px; border-radius: 50%"
/>

<script type="module">
  import cursor from "https://unpkg.com/ipad-cursor@latest"
  cursor.initCursor()
</script>

See Style for full style list.

Use in framework

• Vue.js

  • hooks

    You can use useCursor hook to call updateCursor() automatically on mounted and unmounted.

    <script setup>
    import { useCursor } from "ipad-cursor/vue"
    
    useCursor()
    </script>

  • directive (v0.5.2+)

    Register plugin globally

    // src/main.ts
    import { ipadCursorPlugin } from "ipad-cursor/vue"
    
    app.use(ipadCursorPlugin, {
      // global configurations
      blockStyle: { radius: "auto" }
    })

    Use in component

    <div v-cursor-block />
    <div v-cursor-text />
    <div v-cursor-block="{ background: 'red' }" />

• 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

initCursor(cfg)

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.

updateCursor

Scan element to observe hover event, and apply styles, as well as remove unused element's event listener.

disposeCursor

Remove fake cursor, and remove all event listener, recover default cursor.

updateConfig(cfg)

Update config, see Config for more details.

customCursorStyle(style)

Create style string that can be used as data-cursor-style attribute. This method is used for better type hinting.

resetCursor

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

Default Style

See getDefaultConfig method in index.ts for more details.

Roadmap

• Add Chinese document
• API Docs
• More examples
• Auto detect dom update, and call updateCursor automatically
  • Maybe use MutationObserver

Showcase

• oooo.so
• ipad-cursor.oooo.so

ipad-cursor's Issues

Add a prettier config or disable prettier

Add a config panel to playground that can adjust parameters of cursor

Is it possible to automatically detect the cursor?

Manually specifying whether the cursor is displayed as text seems a bit tricky. Can we automatically change the cursor by the cursor style of the element the cursor is pointing to?

It would probably be written like this:

// target is the dom element
const computedStyle = getComputedStyle(target);
const cursor = computedStyle.cursor;
if (cursor === 'text') {
   ...
} 

I'm not sure if this will have performance issues...

Refactor API design

goals:

• Custom style friendly
• Collation processing logic
• Add more typescript declaration
• Add more JsDoc
• Split core code into separate files

Docs

• Github README (EN)
• Github README (ZH-CN)

how to disable the default cursor style

Reproduce

I've set the data-cursor="block" attribute on both tags

2023-07-23.6.37.58.mov

Description

Could you please tell me how to achieve this effect? I didn't find the solution in documentation :P

2023-07-23.6.35.31.mov

Does not work fine with <NuxtLink />

• When using to jump internally, the cursor cannot be moved.
• This may seem unrelated to updateCursor. But I've implemented the use of a MutationObserver to listen for DOM changes and perform an updateCursor. the cursor is subtly unresponsive for a few seconds before being moved normally.

feat: add lighting effect to block

effect on iPad OS:

RPReplay_Final1688709112.mov

Add a config item called enableLighting (defaults to false), add lighting effect when this config is true

Playground

• Develop
• Deploy

Support for Hexo (NexT theme)

Thanks for this repo!!
Recently, I wanna add this ipad-cursor into my blog built by hexo (NexT theme). But I don't know how to do that :)

Add optional `will-change` support

Just in case the elements lag on less capable devices,
add an optional config to apply will-change for cursor element and block element.

• add configuration enableWillChange
• update docs

will-change on MDN

`scale` is not working before cursor enters a block

  transform:
    translate(calc(-50% + var(--cursor-translateX)), calc(-50% + var(--cursor-translateY)))
    scale(var(--cursor-scale));

--cursor-translateX and --cursor-translateX are first set in onBlockMove(), which will only be triggered when mouse is moving on a block. Therefore, these two CSS variables are undefined before the cursor enters a block, resulting in the transform property being none. Consequently, scale will not work.

Add more convenient way for `vue`

• Vue composables
• v-cursor directive
• Component
  • Maybe IpadCursorProvider, IpadCursor