{"id":19255276,"url":"https://github.com/catsjuice/ipad-cursor","last_synced_at":"2025-05-14T20:08:15.751Z","repository":{"id":179212502,"uuid":"662623212","full_name":"CatsJuice/ipad-cursor","owner":"CatsJuice","description":"● Mouse effect of iPad in browser that can be used in any framework","archived":false,"fork":false,"pushed_at":"2025-01-20T10:27:36.000Z","size":9890,"stargazers_count":439,"open_issues_count":4,"forks_count":14,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-07T04:01:42.451Z","etag":null,"topics":["ipad-cursor","mouse","mouse-emulation"],"latest_commit_sha":null,"homepage":"https://cursor.oooo.so","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CatsJuice.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-05T14:25:14.000Z","updated_at":"2025-04-04T03:10:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"95bff711-e978-4a6b-8120-e70acf4ce7a8","html_url":"https://github.com/CatsJuice/ipad-cursor","commit_stats":null,"previous_names":["catsjuice/ipad-cursor"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatsJuice%2Fipad-cursor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatsJuice%2Fipad-cursor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatsJuice%2Fipad-cursor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatsJuice%2Fipad-cursor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CatsJuice","download_url":"https://codeload.github.com/CatsJuice/ipad-cursor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837064,"owners_count":21169373,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ipad-cursor","mouse","mouse-emulation"],"created_at":"2024-11-09T18:40:04.405Z","updated_at":"2025-04-14T06:40:35.548Z","avatar_url":"https://github.com/CatsJuice.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- Logo --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://cursor.oooo.so/ipad-cursor-dark.svg\"\u003e\n    \u003cimg height=\"100\" src=\"https://cursor.oooo.so/ipad-cursor.svg\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003c!-- Bridge --\u003e\n\u003ch2 align=\"center\"\u003eipad-curosr \u003c/h2\u003e\n\u003c!-- Description --\u003e\n\u003cp align=\"center\"\u003e\n  Mouse effect hacking of iPad in browser that can be used in any frameworks \n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/npm/l/ipad-cursor\"/\u003e\n  \u003cimg src=\"https://img.shields.io/bundlephobia/min/ipad-cursor\"/\u003e\n  \u003cimg src=\"https://img.shields.io/npm/v/ipad-cursor\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"./docs/README.zh.md\"\u003e \n    \u003cimg src=\"https://img.shields.io/badge/language_%E4%B8%AD%E6%96%87-blue\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://cursor.oooo.so\"\u003e\n    \u003cimg src=\"./playground/public/screenshot.gif\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Install\n\n- NPM\n  \n  ```bash\n  npm install ipad-cursor --save\n  ```\n\n- CDN\n\n  Only support `ESM` module\n  \n  ```html\n  \u003cdiv data-cursor=\"block\"\u003eBlock\u003c/div\u003e\n  \u003cdiv data-cursor=\"text\"\u003etext\u003c/div\u003e\n\n  \u003cscript type=\"module\"\u003e\n    import cursor from \"https://unpkg.com/ipad-cursor@latest\"\n    cursor.initCursor()\n  \u003c/script\u003e\n  ```\n\n  See [cursor.oooo.so](https://ipad-cursor.oooo.so) for more details.\n\n## Usage\n\n### Basic usage\n\n  Apply `data-cursor` attribute to the element you want to add the effect.\n  \n  - `data-cursor=\"text\"`: text cursor\n  - `data-cursor=\"block\"`: block cursor \n\n  ```html\n  \u003cdiv data-cursor=\"text\"\u003eText Cursor\u003c/div\u003e\n  \u003cdiv data-cursor=\"block\"\u003eBlock Cursor\u003c/div\u003e\n  ```\n\n  After your dom loaded, call `initCursor` to start the effect. You may need to call `updateCursor()` when dom updated.\n\n  ```js\n  import { initCursor } from 'ipad-cursor'\n\n  initCursor()\n  ```\n\n  \u003e ⚠️ **Notice**: As so far, you need to manage `when to updateCursor` yourself. Make sure to call `updateCursor` after dom updated.\n  \u003e In the future, there maybe a better way to handle this, see [Roadmap](#roadmap) for more details.\n\n### Custom Style\n\n  You can customize the style of the cursor by [Config](#config), config can be passed to `initCursor` method, or use `updateConfig` method to update config. Every type can be configured separately.\n\n  ```ts\n  import { initCursor, updateConfig } from 'ipad-cursor'\n  import type { IpadCursorConfig, IpadCursorStyle } from 'ipad-cursor'\n\n  const normalStyle: IpadCursorStyle = { background: 'red' }\n  const textStyle: IpadCursorStyle = { background: 'blue' }\n  const blockStyle: IpadCursorStyle = { background: 'green' }\n  const config: IpadCursorConfig = {\n    normalStyle,\n    textStyle,\n    blockStyle,\n  };\n  initCursor(config)\n  ```\n\n  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.\n\n  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`.\n\n  It is recommended to use [customCursorStyle](#customCursorStyle%28style%29) method to create style string.\n\n  For example, customize the style for a circle element (Like avatar).\n\n  ```html\n  \u003cdiv \n    data-cursor=\"block\" \n    data-cursor-style=\"radius: 50%\" \n    style=\"width: 50px; height: 50px; border-radius: 50%\"\n  /\u003e\n\n  \u003cscript type=\"module\"\u003e\n    import cursor from \"https://unpkg.com/ipad-cursor@latest\"\n    cursor.initCursor()\n  \u003c/script\u003e\n  ```\n\n  See [Style](#style) for full style list.\n\n### Use in framework\n\n- [Vue.js](https://vuejs.org/)\n  - **hooks**\n\n    You can use `useCursor` hook to call `updateCursor()` automatically on mounted and unmounted.\n    ```ts\n    \u003cscript setup\u003e\n    import { useCursor } from \"ipad-cursor/vue\"\n\n    useCursor()\n    \u003c/script\u003e\n    ```\n  - **directive** (v0.5.2+)\n\n    Register plugin globally\n    ```ts\n    // src/main.ts\n    import { ipadCursorPlugin } from \"ipad-cursor/vue\"\n\n    app.use(ipadCursorPlugin, {\n      // global configurations\n      blockStyle: { radius: \"auto\" }\n    })\n    ```\n\n    Use in component\n    ```html\n    \u003cdiv v-cursor-block /\u003e\n    \u003cdiv v-cursor-text /\u003e\n    \u003cdiv v-cursor-block=\"{ background: 'red' }\" /\u003e\n    ```\n\n- [React](https://react.dev)\n  See [App.tsx](./examples/react-basic/src/App.tsx)\n- [Hexo](https://hexo.io/)\n  See [@zqqcee](https://github.com/zqqcee)'s [Blog](https://zqqcee.github.io/2023/07/23/ebae3e5deab8/)\n\n## Principle\n\nWhen `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.\n\nAfter init finished, it will call `updateCursor` method, scan element with `data-cursor` attribute, detect the cursor type, and add event listener to the element.\n\nWhen mouse enter the element, apply styles.\n\n## API\n\n### initCursor(cfg)\n  \u003e see [Config](#config) for more details.\n\n  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.\n\n\n### updateCursor\n  Scan element to observe hover event, and apply styles, as well as remove unused element's event listener.\n\n### disposeCursor\n  Remove fake cursor, and remove all event listener, recover default cursor.\n\n### updateConfig(cfg)\n  Update config, see [Config](#config) for more details.\n\n### customCursorStyle(style)\n  Create style string that can be used as `data-cursor-style` attribute.\n  This method is used for better type hinting.\n\n### resetCursor\n  Reset cursor to default style.\n\n## Config\n\nIt is recommended to see [index.d.ts](./src/index.d.ts) in the npm package.\n\n| Name                                              | Type              | Default             | Description                                                                            | required |\n| ------------------------------------------------- | ----------------- | ------------------- | -------------------------------------------------------------------------------------- | -------- |\n| `adsorptionStrength`                              | `number`          | `0.2`               | The strength of adsorption effect, number between 0 and 30                             | No       |\n| `className`                                       | `string`          | `'ipad-cursor'`     | The class name of fake cursor                                                          | No       |\n| `blockPadding`                                    | `number`          | `auto`              | The padding of cursor when hover on block, set to `auto` will calculate  automatic     | No       |\n| `enableAutoTextCursor`(`v0.2.0+`)                 | `boolean`         | `false`             | Auto detect text cursor, see [#12](https://github.com/CatsJuice/ipad-cursor/pull/12)   | No       |\n| `enableLighting`(`v0.3.0+`)                       | `boolean`         | `false`             | Add a lighting effect to block [#14](https://github.com/CatsJuice/ipad-cursor/pull/14) | No       |\n| `enableMouseDownEffect`(`v0.4.3+`,  Experimental) | `boolean`         | `false`             | Add a effect when mouse down, customize style by config `mouseDownStyle`               | No       |\n| `enableAutoUpdateCursor`(`v0.5.0+`)               | `boolean`         | `false`             | Auto update cursor when dom updated                                                    | No       |\n| `normalStyle`                                     | `IpadCursorStyle` | see [Style](#style) | The style of normal cursor, see [Style](#style)                                        | No       |\n| `textStyle`                                       | `IpadCursorStyle` | see [Style](#style) | The style of text cursor, see [Style](#style)                                          | No       |\n| `blockStyle`                                      | `IpadCursorStyle` | see [Style](#style) | The style of block cursor, see [Style](#style)                                         | No       |\n| `mouseDownStyle`(`v0.4.3+`, Experimental)         | `IpadCursorStyle` | see [Style](#style) | The style of cursor when mouse is pressed, see [Style](#style)                         | No       |\n\n## Style\n\n| Name                     | Type                    | Description                                                                                                                                          | example                            |\n| ------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |\n| `width`                  | `MaybeSize`             | The width of cursor                                                                                                                                  | `'10px'`, `10`, `'10'`             |\n| `height`                 | `MaybeSize`             | The height of cursor                                                                                                                                 | `'10px'`, `10`, `'10'`             |\n| `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'`   |\n| `background`             | `string`                | The background color of cursor                                                                                                                       | `'#fff'`, `'red'`, `'rgba(0,0,0)'` |\n| `border`                 | `string`                | The css border property of cursor                                                                                                                    | `'1px solid black'`                |\n| `zIndex`                 | `number`                | The z-index of cursor                                                                                                                                | `1`                                |\n| `scale`                  | `number`                | The scale of cursor                                                                                                                                  | `1.05`                             |\n| `backdropBlur`           | `MaybeSize`             | The backdrop-filter blur of cursor                                                                                                                   | `'10px'`, `10`, `'10'`             |\n| `backdropSaturate`       | `string`                | The backdrop-filter saturate of cursor                                                                                                               | `180%`                             |\n| `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` |\n| `durationPosition`       | `MaybeDuration`         | Transition duration of position properties like `top`, `left`, if unit if not  specified, `ms` will be used                                          | `'1000'`, `1000`, `200ms`, `0.23s` |\n| `durationBackdropFilter` | `MaybeDuration`         | Transition duration of backdrop-filter property, if unit if not  specified, `ms` will be used                                                        | `'1000'`, `1000`, `200ms`, `0.23s` |\n\n### Default Style\n\nSee `getDefaultConfig` method in [index.ts](./src/index.ts) for more details.\n\n\n## Roadmap\n\n- [x] Add Chinese document\n- [x] API Docs\n- [ ] More examples\n- [x] Auto detect dom update, and call `updateCursor` automatically\n    - Maybe use [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)\n\n\n## Showcase\n\n- [oooo.so](https://oooo.so)\n- [ipad-cursor.oooo.so](https://ipad-cursor.oooo.so)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatsjuice%2Fipad-cursor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatsjuice%2Fipad-cursor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatsjuice%2Fipad-cursor/lists"}