{"id":16788760,"url":"https://github.com/markmead/custom-cursor","last_synced_at":"2025-03-22T00:33:00.475Z","repository":{"id":34878756,"uuid":"186467241","full_name":"markmead/custom-cursor","owner":"markmead","description":"This is a tiny JavaScript package that creates custom cursor for you with minimal JavaScript and allows you to write hover effects for the cursor(s) in CSS 👆","archived":false,"fork":false,"pushed_at":"2025-03-07T13:44:31.000Z","size":295,"stargazers_count":23,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T06:47:35.507Z","etag":null,"topics":["cursor","custom-cursor","interactive"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/markmead.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":"2019-05-13T17:36:32.000Z","updated_at":"2025-03-17T20:18:57.000Z","dependencies_parsed_at":"2024-10-28T12:16:08.827Z","dependency_job_id":"b477efe9-e506-4ebb-a07d-bfa2e7d7d279","html_url":"https://github.com/markmead/custom-cursor","commit_stats":{"total_commits":51,"total_committers":3,"mean_commits":17.0,"dds":0.1568627450980392,"last_synced_commit":"3090230570c0194bc7d4cab59903271466770702"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmead%2Fcustom-cursor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmead%2Fcustom-cursor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmead%2Fcustom-cursor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmead%2Fcustom-cursor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markmead","download_url":"https://codeload.github.com/markmead/custom-cursor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244890102,"owners_count":20527030,"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":["cursor","custom-cursor","interactive"],"created_at":"2024-10-13T08:24:41.637Z","updated_at":"2025-03-22T00:33:00.470Z","avatar_url":"https://github.com/markmead.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Custom Cursor 👆\n\n![](https://img.shields.io/bundlephobia/min/custom-cursor)\n![](https://img.shields.io/npm/v/custom-cursor)\n![](https://img.shields.io/npm/dt/custom-cursor)\n![](https://img.shields.io/github/license/markmead/custom-cursor)\n\nThis is a tiny JavaScript package that creates custom cursor for you with\nminimal JavaScript and allows you to write hover effects for the cursor(s) in\nCSS.\n\n## Features\n\n- 🪶 Lightweight (\u003c 1kb minified)\n- 🎨 Fully customizable with CSS\n- ⚡ Simple API with minimal configuration\n- 🔄 Multiple cursor support for follow-along effects\n- 🎯 Target specific elements for custom hover states\n- 📱 Works with mouse and touch devices\n\nPerfect for creative websites, portfolios, and interactive experiences where you\nwant to replace the default cursor with something more engaging.\n\n## Install\n\n## CDN\n\nFor this package to work with a CDN, you'll need to access the `Cursor` class\nfrom the `window` object.\n\n```html\n\u003cscript\n  defer\n  src=\"https://unpkg.com/custom-cursor@latest/dist/cdn.min.js\"\n\u003e\u003c/script\u003e\n\n\u003cscript\u003e\n  document.addEventListener('DOMContentLoaded', () =\u003e {\n    new window['Cursor']({})\n  })\n\u003c/script\u003e\n```\n\n### Configuration with CDN\n\nWhen using the CDN version, you still have full access to all configuration\noptions:\n\n```js\ndocument.addEventListener('DOMContentLoaded', () =\u003e {\n  new window['Cursor']({\n    count: 3, // Creates multiple cursor elements\n    targets: ['a', 'button', '.interactive'], // Elements that trigger hover states\n  })\n})\n```\n\nThese options work exactly the same way as in the package version, giving you\ncomplete control over your custom cursor behavior.\n\n## Package\n\n```shell\nyarn add -D custom-cursor\nnpm install -D custom-cursor\n```\n\n```js\nimport Cursor from 'custom-cursor'\n\nnew Cursor({})\n```\n\n## Options\n\nThe `Cursor` constructor accepts an optional configuration object with two\nparameters:\n\n```js\nnew Cursor({\n  count: 5, // Creates multiple cursor elements\n  targets: ['a', '.title', '#header'], // Elements that trigger hover states\n})\n```\n\nBoth parameters are optional and can be customized to fit your specific\nrequirements.\n\n### Count\n\nThis parameter lets you specify the number of cursor elements to create, which\nis ideal for creating trailing cursor effects.\n\nWhen you set `count: 5`, the package generates the following HTML structure:\n\n```html\n\u003cdiv data-cursor=\"0\" style=\"...\"\u003e\u003c/div\u003e\n\u003cdiv data-cursor=\"1\" style=\"...\"\u003e\u003c/div\u003e\n\u003cdiv data-cursor=\"2\" style=\"...\"\u003e\u003c/div\u003e\n\u003cdiv data-cursor=\"3\" style=\"...\"\u003e\u003c/div\u003e\n\u003cdiv data-cursor=\"4\" style=\"...\"\u003e\u003c/div\u003e\n```\n\nEach cursor element receives a `data-cursor` attribute with its index number,\nallowing you to style each cursor element individually with CSS:\n\n```css\n[data-cursor] {\n  width: 20px;\n  height: 20px;\n}\n\n[data-cursor='0'] {\n  background: #00f;\n}\n\n[data-cursor='1'] {\n  background: #eee;\n}\n```\n\nThis approach gives you complete control over the appearance of each cursor in\nthe sequence, creating trailing effects, size variations, or color gradients.\n\n### Targets\n\nThe `targets` parameter lets you define specific HTML elements that will trigger\ncursor hover effects.\n\nFor example, with `targets: ['a', '.title', '#header']`, the package will:\n\n1. Locate all `\u003ca\u003e` elements, elements with the class `.title`, and the element\n   with ID `#header`\n2. Add event listeners for `mouseover` and `mouseleave` on these elements\n3. When the mouse hovers over a target, add a class of `cursor-hover--\u003ctarget\u003e`\n   to the document body\n\nThe `\u003ctarget\u003e` portion of the class name corresponds to the identifier in your\ntargets array. For instance, hovering over `.title` elements will add\n`cursor-hover--title` to the body.\n\n#### Creating Hover Styles\n\nYou can style cursor hover states using the added class names. For example:\n\n```css\n/* Style all cursors when hovering over links */\n.cursor-hover--a [data-cursor] {\n}\n\n/* Style all cursors when hovering over elements with .title class */\n.cursor-hover--title [data-cursor] {\n}\n\n/* Style all cursors when hovering over element with #header ID */\n.cursor-hover--header [data-cursor] {\n}\n\n/* Style specific cursors by index during hover */\n.cursor-hover--header [data-cursor='0'] {\n}\n\n.cursor-hover--header [data-cursor='1'] {\n}\n```\n\nThis approach gives you fine-grained control over cursor appearance during\ndifferent hover interactions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmead%2Fcustom-cursor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkmead%2Fcustom-cursor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmead%2Fcustom-cursor/lists"}