@supalosa/osrs-react-ui

Composable, unconnected React components for Old School RuneScape-style user interfaces. This package does not depend on osrs-sdk and can be connected to any application state or game engine.

Credits

Original Old School RuneScape visual design, sprites, and fonts are by Jagex Ltd. The React component implementation is by Supalosa. This is an unofficial project and is not endorsed by or affiliated with Jagex.

The library currently includes resizable modern and resizable classic layout shells, minimap chrome, side panels, interface tabs, display settings, and an interactive 28-slot inventory. Fixed classic can reuse the same low-level components when its layout shell is implemented.

Development

Requires Node.js 20.20 or newer.

npm ci
npm run storybook

Run all local checks with:

npm run check

Installation

npm install @supalosa/osrs-react-ui

import { RuneScapeButton, RuneScapePanel } from "@supalosa/osrs-react-ui";
import "@supalosa/osrs-react-ui/styles.css";

The library build owns its resource-pack images. Applications do not need to copy them into a public directory.

Resizable modern

The layout components are controlled and intentionally contain no game-engine state. Supply the world/minimap content and keep the selected tab in the host:

import { useState } from "react";
import {
  Inventory,
  interfaceTabIcons,
  ResizableModernLayout,
  ResizableModernMinimap,
  ResizableModernSidePanel,
} from "@supalosa/osrs-react-ui";

const tabs = [
  { id: "inventory", label: "Inventory", icon: interfaceTabIcons.inventory },
  { id: "options", label: "Settings", icon: interfaceTabIcons.options },
];

export function GameInterface() {
  const [activeTab, setActiveTab] = useState<string | null>("inventory");

  return (
    <ResizableModernLayout
      world={<canvas />}
      minimap={<ResizableModernMinimap>{/* minimap renderer */}</ResizableModernMinimap>}
      sidePanel={
        <ResizableModernSidePanel
          activeTab={activeTab}
          onActiveTabChange={setActiveTab}
          tabs={tabs}
        >
          {(tab) => tab === "inventory" ? <Inventory /> : <Settings />}
        </ResizableModernSidePanel>
      }
    />
  );
}

Selecting the active tab again collapses the panel. Storybook's Interfaces/Resizable Modern stories include an opacity-controlled overlay of the supplied reference screenshots for pixel alignment work.

Both resizable layout shells accept stretchPercent, from 0 at native size to 100 at twice the native size. Minimap, chat, and side-panel chrome scale from their respective screen anchors.

Inventory

Inventory state remains owned by the consuming application. Supply up to 28 items in slot order and handle clicks or completed drag movements as needed:

<Inventory
  items={items}
  onItemLeftClick={(slot) => useItem(slot)}
  onItemMoved={(fromSlot, toSlot) => reorderItem(fromSlot, toSlot)}
/>

The component provides the press and drag visuals, including stack quantities, but does not decide the resulting inventory state.

Equipment

The equipment tab reports clicks on both occupied and empty slots through onSlotLeftClick. The callback receives the slot name (for example, "weapon"); the consuming application can use its equipment map to decide whether to equip or remove an item. Empty slots become buttons when the callback is supplied.

Bundler setup

Vite

No additional asset configuration is expected. Import the package stylesheet once from the application entry point.

Webpack

The application must process imported CSS. A typical Webpack rule uses style-loader and css-loader:

{
  test: /\.css$/,
  use: ["style-loader", "css-loader"],
}

Publishing

The package is configured for public npm publication with provenance. Licensing and attribution for bundled third-party visual assets must be resolved before the first published release. Once resolved, verify and inspect the package with:

npm run check
npm pack --dry-run