OSRS Icons

A collection of Old School RuneScape icons as ready-to-use CSS cursor values. Import only what you need — unused icons are automatically tree-shaken from your bundle.

📖 Browse icons & build packs →

Installation

npm install @dava96/osrs-icons

Or use it directly from a CDN with no build step:

<script type="module">
  import { abyssalWhip } from 'https://esm.sh/@dava96/osrs-icons';

  document.body.style.cursor = abyssalWhip;
</script>

Quick Start

import { abyssalWhip, toDataUrl } from '@dava96/osrs-icons';

// Use as a CSS cursor
<div style={{ cursor: abyssalWhip }}>Hover me!</div>

// Use as an image
<img src={toDataUrl(abyssalWhip)} alt="Abyssal Whip" />

Every icon export is a fully formed CSS cursor value (url('data:image/png;base64,...'), auto), so you can drop it straight into any cursor property.

Icons

The package contains ~19,500 icons from two sources, all exported as individual named exports for full tree-shaking support:

Inventory Icons (~17,400)

Item sprites from the in-game inventory:

import { abyssalWhip, dragonScimitar } from '@dava96/osrs-icons';

element.style.cursor = abyssalWhip;

Category Icons (~2,100)

UI icons from the OSRS Wiki — skill icons, prayer icons, map markers, spell icons, and more. These are imported the exact same way as inventory icons:

import { combatIcon, prayerAugury } from '@dava96/osrs-icons';

element.style.cursor = combatIcon;
element.style.cursor = prayerAugury;

Note: In the rare case of a name collision between collections, the category icon is suffixed with Category (e.g. hunterKitCategory).

Discovering Icons

Browse icons programmatically or restrict values to valid names with TypeScript types:

import {
  iconNames, // all inventory icon names
  categoryIconNames, // all category icon names
  type IconName,
  type CategoryIconName,
} from '@dava96/osrs-icons';

// Search / autocomplete
const results = iconNames.filter((name) => name.includes('dragon'));

// Type-safe references
function setCustomCursor(name: IconName) {
  /* ... */
}

Using Icons as Images

Use the toDataUrl helper to extract the raw data:image/png;base64,... URL for use outside of CSS — for example, as an <img> src or a CSS background-image:

import { abyssalWhip, dragonScimitar, toDataUrl } from '@dava96/osrs-icons';

// Single icon
<img src={toDataUrl(abyssalWhip)} alt="Abyssal Whip" />

// Multiple icons at once
const urls = toDataUrl({
  whip: abyssalWhip,
  sword: dragonScimitar,
});
// urls.whip  → "data:image/png;base64,..."
// urls.sword → "data:image/png;base64,..."

Cursor Packs

Pre-built thematic icon groups. Each pack groups related icons by their in-game state and includes a stages array for sequential use (e.g. loading indicators):

import { runePack, bucketPack, coinsPack } from '@dava96/osrs-icons';

// Individual keys
element.style.cursor = runePack.air;

// Sequential stages — great for loading indicators
const stages = bucketPack.stages; // [empty, 1/5, 2/5, 3/5, 4/5, full]
const index = Math.min(Math.floor((progress / 100) * stages.length), stages.length - 1);
element.style.cursor = stages[index];

Available packs:

| Pack | Keys | | ------------ | ----------------------------------------------------------------------------------------------- | | coinsPack | _1 to _10000 + stages[] | | bucketPack | empty to full + stages[] | | runePack | air, fire, water, earth, chaos, mind, death, law, nature, body + stages[] |

Utilities

flipCursor — Mirror Icons Horizontally

Many OSRS sprites face right, but cursors typically point left. Flip a single icon, an array, or an entire pack:

import { abyssalWhip, runePack, flipCursor } from '@dava96/osrs-icons';

// Single icon
const leftFacing = await flipCursor(abyssalWhip);

// Array of icons
const [flippedAir, flippedFire] = await flipCursor([runePack.air, runePack.fire]);

// Entire pack — flips all values and stages in one call
const flippedRunes = await flipCursor(runePack);

Results are cached internally — flipping the same icon twice returns instantly. Browser-only (uses Canvas API); returns the original value in Node.js/SSR.

applyCursors — Map Icons to CSS Cursor States

Override standard CSS cursor states (default, pointer, wait, etc.) with OSRS icons globally or scoped to a specific element:

import { abyssalWhip, dragonScimitar, applyCursors } from '@dava96/osrs-icons';

// Apply globally
const cleanup = applyCursors({
  default: abyssalWhip,
  pointer: dragonScimitar,
});

// Later, revert to browser defaults
cleanup();

Scope to a specific element:

applyCursors({ default: abyssalWhip }, document.getElementById('game-area')!);

animateCursor — Animated Sprite Cursors

Cycle through a sequence of icons as an animated cursor using pure CSS @keyframes — no JavaScript timers required:

import { coinsPack, animateCursor } from '@dava96/osrs-icons';

// Animate a growing coin stack on the whole page
const stop = animateCursor(coinsPack.stages, { duration: 1200 });

// Stop and clean up
stop();

Scope to an element and limit iterations:

import { bucketPack, animateCursor } from '@dava96/osrs-icons';

const stop = animateCursor(bucketPack.stages, {
  duration: 900,
  target: document.getElementById('loading')!,
  iterations: 3,
});

Requires at least 2 frames. Browser-only; returns a no-op cleanup in Node.js/SSR.

errorCursor — Easter Egg 🐟

An alias for the Red Herring icon — a fun cursor for error states:

import { errorCursor } from '@dava96/osrs-icons';

element.style.cursor = errorCursor;

API Reference

Functions

| Function | Signature | Description | | --------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | | toDataUrl | (cursor: string) → string | Extracts the raw data:image/png;base64,... URL from a CSS cursor value | | toDataUrl | (cursors: Record<K, string>) → Record<K, string> | Batch version — extracts URLs from an object of cursor values | | flipCursor | (cursor: string) → Promise<string> | Flips a single icon horizontally. Cached. Browser-only. | | flipCursor | (cursors: string[]) → Promise<string[]> | Flips an array of icons horizontally | | flipCursor | (pack: Record) → Promise<Record> | Flips all values and stages in a pack | | applyCursors | (mapping: CursorMapping, target?: HTMLElement) → () => void | Injects CSS rules mapping cursor states to icons. Returns a cleanup function. | | animateCursor | (frames: string[], options?: AnimateCursorOptions) → () => void | Animates a cursor through a frame sequence via CSS keyframes. Returns cleanup. |

Types

| Type | Description | | ---------------------- | -------------------------------------------------------------------------- | | IconName | Union of all inventory icon export names | | CategoryIconName | Union of all category icon export names | | CursorState | Standard CSS cursor states ('default', 'pointer', 'wait', etc.) | | CursorMapping | Partial<Record<CursorState, string>> — maps cursor states to icon values | | AnimateCursorOptions | { duration?: number, target?: HTMLElement, iterations?: number } |

Constants

| Export | Type | Description | | ------------------- | ------------------------ | ---------------------------------------------------------- | | iconNames | readonly string[] | Array of all inventory icon export names (~17,400) | | categoryIconNames | readonly string[] | Array of all category icon export names (~2,100) | | errorCursor | string | Alias for redHerring | | *Pack | Record<string, string> | Pre-built cursor packs (see Cursor Packs) |

Browser Compatibility

| Feature | Browser | Node.js / SSR | | --------------- | ---------------------- | ------------------------- | | Icon imports | ✅ All | ✅ All | | toDataUrl | ✅ All | ✅ All | | applyCursors | ✅ All modern | ⚠️ Returns no-op cleanup | | flipCursor | ✅ Canvas API required | ⚠️ Returns original value | | animateCursor | ✅ All modern | ⚠️ Returns no-op cleanup | | Cursor packs | ✅ All | ✅ All |

All features are SSR-safe — browser-only utilities degrade gracefully by returning safe fallback values.

How It Works

Two build scripts fetch every icon from the OSRS Wiki and generate TypeScript source files:

| Script | Source Category | Output | Icons | | ----------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------- | ------- | | update-icons | Item inventory images | src/generated/icons.ts | ~17,400 | | update-category-icons | Icons (+ all subcategories, crawled recursively) | src/generated/category-icons.ts | ~2,100 |

Both scripts share common utilities from scripts/shared.ts and use an MD5-keyed disk cache so that subsequent runs only download new or changed images. SVGs are automatically rasterised to 32×32 PNGs.

Each icon is a small ~32×32 pixel sprite, base64-encoded inline — no external assets to host.

Package Output

| Format | Path | Use | | ------ | --------------------- | ------------------------------------ | | ESM | dist/esm/index.js | import (bundlers, modern browsers) | | CJS | dist/cjs/index.js | require() (Node.js, legacy) | | Types | dist/cjs/index.d.ts | TypeScript definitions |

The package has "sideEffects": false for optimal tree-shaking in Webpack, Rollup, Vite, and esbuild.

Contributing

See CONTRIBUTING.md for development setup, project structure, and automation details.

License

This project is not affiliated with Jagex Ltd. Icons are the property of Jagex/OSRS Wiki. OSRS Wiki content is available under CC BY-NC-SA 3.0.