essential-cursors

v1.1.0

Published

15 days ago

Essential Cursor — professional SVG cursor system by Essential Web Tools

Downloads

1,172

0High
0Medium
0Low

essential-web-tools

cursor cursors svg css pointer design-system accessibility cdn

🚀 Why Essential Cursor?

Stop settling for default, ugly, or inaccessible system cursors. Essential Cursor brings 41 beautifully crafted, pixel-perfect SVG cursors to your web application using pure CSS.

No JavaScript. No heavy bundles. No layout shifts. Just drop in a single CSS file and get instant access to a professional, accessible, and highly customizable cursor ecosystem.

✨ Key Features:

🎨 41 Pixel-Perfect SVGs: From standard pointers to complex resize and rotation tools.
⚡ Zero JavaScript: Blazing fast, pure CSS implementation.
🌗 Auto Dark/Light Mode: Seamlessly adapts to user preferences.
♿ WCAG 2.2 Compliant: Built with accessibility at its core (High contrast, target sizes, reduced motion).
📦 Microscopic Footprint: Under 6KB gzipped.
🤖 AI-Ready: Explicit context for LLMs to generate perfect code.

🖱️ Grouped Gallery

Selection & Pointers

Hands & Rotation

Resize

Objects & Tools

Zoom & Navigation

⚡ Installation

jsDelivr (Recommended CDN)

<!-- Pinned version with Subresource Integrity (SRI) -->
<link 
  rel="stylesheet" 
  href="https://cdn.jsdelivr.net/npm/[email protected]/dist/essential-cursors.min.css"
  integrity="sha384-qQ60ujaappdzuW5KRSu9rFuVDwc034aCozapGOQoqsuhGJgx04b3Ai6V5uZ87Zp+"
  crossorigin="anonymous">

🔐 Always use SRI in production. Hashes are available in dist/integrity.json.

unpkg

<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/essential-cursors.min.css">

npm

npm install essential-cursors

/* In your CSS bundle */
@import 'essential-cursors/dist/essential-cursors.css';
/* or */
@import 'essential-cursors';

🎯 Usage

Mode 1: Utility Classes

<button class="ec-pointer">Click here</button>
<div class="ec-grab">Drag this element</div>
<span class="ec-wait">Loading...</span>

Mode 2: `data-cursor` Attribute

<div data-cursor="zoom-in">Zoom in</div>
<div data-cursor="rotate">Rotate</div>
<div data-cursor="text-select">Select text</div>

Mode 3: CSS Variables (Tokens)

.element {
  cursor: var(--ec-pointer);
}

.zoomable {
  cursor: var(--ec-zoom-in);
}

.movable {
  cursor: var(--ec-move);
}

🤖 AI Context & Prompt Instructions

For LLMs and AI Agents: This section provides exact context to help you generate correct implementation code for this library.

Library Name: essential-cursors
Architecture: Pure CSS (No JS runtime required).
Core Mechanism: Maps CSS variables (--ec-*) to data-URIs containing SVG cursors, with native CSS cursor keywords as mandatory fallbacks.
How to generate code:
1. Prefer Utility Classes (ec-[name]) for direct HTML implementation.
2. Use CSS Variables (var(--ec-[name])) when writing custom CSS stylesheets.
3. Toggle themes by adding data-theme="dark" or data-cursor-theme="dark" to the <html> tag or any parent container.

🌗 Theming

The library automatically supports two visual themes:

Light Theme (Default): Icon silhouette with a thin, soft white halo.
Dark Theme: Same icon with its own halo color/tuning, kept legible over dark backgrounds.

Activation

<!-- Dark theme via data-theme -->
<html data-theme="dark">

<!-- OR via data-cursor-theme -->
<html data-cursor-theme="dark">

/* Force dark theme on a specific container */
.dark-section {
  --ec-theme: dark;
}

Cursors automatically swap using [data-theme="dark"] and [data-cursor-theme="dark"] selectors.

Halo Style (Editable)

Every cursor icon is rendered with a thin, soft halo/outline behind it so it stays visible on any background. The halo is generated at build time from a single config object in scripts/build.mjs, so it's fully editable without touching each SVG:

// scripts/build.mjs
const HALO_CONFIG = {
  radius: 1,        // outline thickness - lower = thinner
  blur: 0.6,         // outline softness - higher = softer/smoother edge
  colorLight: '#ffffff',
  colorDark: '#ffffff',
};

After changing any value, regenerate the CSS with:

npm run build

🖱️ Auto-click Cursor

Opt-in behavior that automatically swaps the browser's default pointer/default cursor for this library's click cursor on typical interactive elements (a, button, [role="button"], form controls, [onclick], focusable [tabindex], etc.) - no JavaScript required.

<!-- Enable everywhere -->
<html data-cursor-auto>

<!-- Or scope it to a section -->
<div data-cursor-auto>
  <a href="#">This link uses the click cursor</a>
</div>

To keep the browser's native cursor on a specific element even inside an auto-click area, add data-cursor-native to it (or to an ancestor):

<div data-cursor-auto>
  <a href="#">Uses --ec-click</a>
  <a href="#" data-cursor-native>Keeps the native browser cursor</a>
</div>

♿ Accessibility

Essential Cursor strictly follows WCAG 2.2 guidelines and the CSS UI Level 4 specification:

Met Criteria

1.4.11 Non-text Contrast (AA): Minimum 3:1 contrast between cursors and backgrounds.
2.3.3 Target Size (AAA): 60×60px grid with adequate touch area.
CSS UI Level 4: Mandatory fallback keywords in all tokens.

Reduced Motion

@media (prefers-reduced-motion: reduce) {
  /* Static cursors, no animations */
  * {
    cursor: auto !important;
  }
}

Forced Colors (High Contrast Mode)

@media (forced-colors: active) {
  /* Cursors respect system colors */
  [data-cursor] {
    forced-color-adjust: auto;
  }
}

Native Fallbacks

Every CSS token includes a native fallback keyword:

--ec-pointer: url("data:image/svg+xml,...") 30 8, pointer;
/* If SVG fails, browser falls back to native 'pointer' */

📦 Bundle Size

| File | Raw Size | Gzip Size | |---------|-----------------|----------------| | essential-cursors.css | ~66 KB | ~6 KB | | essential-cursors.min.css | ~65 KB | ~6 KB |

Goal achieved: < 6 kB gzip ✅

🧰 Contributing

Workflow

Create/Edit SVG in src/svg/cursor-name.svg
- viewBox="0 0 60 60"
- Silhouette in #111111
- Round linejoin/linecap
- 2px padding on edges

Update hotspots.json

{
  "cursor-name": [x, y, "fallback-keyword"]
}

Run Build
```
npm run build
```
Run Tests
```
npm test
```
Validate Diff
```
git diff --exit-code dist
```

Requirements

Node.js >= 20
Zero external dependencies (build uses native modules only)

🔒 Repository Security Recommendations

To maintain supply chain security:

GitHub

Branch Protection on main
- Require review before merge
- Require green CI (ci.yml workflow)
- Block force push
Signed Tags
```
git tag -s v1.1.0 -m "Release v1.1.0"
```
Dependabot active for security updates

npm

Mandatory 2FA for publishing
```
npm profile set requires-auth always
```
Automatic Provenance (already enabled in package.json)
- Ensures package was published from this specific repository

📄 License

BSD-3-Clause with Additional Conditions

See LICENSE file for full details.

Key terms:

✅ Commercial and non-commercial use allowed
✅ Modification and redistribution allowed
⚠️ Clause 4: Transfer to "Essential Web Tools" or affiliates is prohibited
⚠️ Clause 5: Limitation of liability extends to all contributors