The ultimate pure CSS SVG cursor library. CDN-ready, fully themeable, and strictly WCAG 2.2 compliant.
Part of the Essential Web Tools ecosystem. Building the foundational layers of the modern web.
---
## 🚀 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
default
pointer
click
crosshair
text
text-select
not-allowed
help
wait
eyedropper
location-pin
### Hands & Rotation
grab
grabbing
pan
hand-rotate
rotate
rotate-object
rotate-selection
### Resize
n-resize
ne-resize
e-resize
se-resize
s-resize
sw-resize
w-resize
nw-resize
ns-resize
ew-resize
nesw-resize
nwse-resize
### Objects & Tools
move
add
add-object
copy-object
duplicate-object
pencil
pencil-add
scale-object
### Zoom & Navigation
zoom
zoom-in
zoom-out
---
## ⚡ Installation
### jsDelivr (Recommended CDN)
```html
```
> 🔐 **Always use SRI in production.** Hashes are available in [`dist/integrity.json`](dist/integrity.json).
### unpkg
```html
```
### npm
```bash
npm install essential-cursors
```
```css
/* In your CSS bundle */
@import 'essential-cursors/dist/essential-cursors.css';
/* or */
@import 'essential-cursors';
```
---
## 🎯 Usage
### Mode 1: Utility Classes
```html
```
### Mode 3: CSS Variables (Tokens)
```css
.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 `` 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
```html
```
```css
/* 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:
```js
// 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:
```bash
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.
```html
```
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):
```html
