CatsJuice/ipad-cursor

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.

Style

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