NippleJS v1.0.0

A complete ground-up rewrite of NippleJS — now TypeScript-first, zero dependencies, with a modern build pipeline and a brand new documentation website.

🌐 Documentation · 🎮 Interactive Demos · 📦 npm

---

✨ New Features

color: { front, back } — Full visual control

The color option now accepts a string or a { front, back } object. Since it sets the CSS background property, gradients, images, and any CSS background value work out of the box. (f244978)

:::js
nipplejs.create({
    color: {
        front: 'linear-gradient(135deg, #818cf8, #38bdf8)',
        back: 'radial-gradient(circle, rgba(99,102,241,0.15) 40%, transparent)',
    },
});

collection.reposition() + automatic ResizeObserver

Manually recalculate the zone bounding box and joystick positions after layout changes. The zone is also automatically watched with a ResizeObserver, so most resize scenarios are handled without any code. See the API docs. (075ab9b)

:::js
manager.reposition();

baseDelta in move event data (follow: true)

When the joystick base follows the thumb past the radius, the move event now includes baseDelta: { x, y } — the per-frame displacement of the base. Use vector for fine control and baseDelta for camera/world panning. See it in action in the Space Observatory demo. (f9e2095, 6b94695)

:::js
manager.on('move', (evt) => {
    const { vector, baseDelta } = evt.data;
    camera.x += baseDelta.x * panSpeed;
});

logLevel API

Control the library's console output globally. See the Logging docs. (f6b6ca8)

:::js
nipplejs.setLogLevel('debug');   // all logs
nipplejs.setLogLevel('warning'); // warnings and errors (default)
nipplejs.setLogLevel('none');    // silent
nipplejs.getLogLevel();          // returns current level

Zone position warning

The library now warns at creation time if the zone element has position: static, which causes joysticks to be positioned incorrectly. (f84205d)

move event fires continuously

The move event now fires on every pointermove, not only when the direction changes. This was a long-standing bug in v0. See the Events reference. (c438f2b)

---

🐛 Bug Fixes

• Multitouch broken on mobile — preventDefault() on pointerdown interfered with dual-stick setups. Now only called on move events; touch-action: none on the zone handles the rest. (ca330c4)
• _domHandlers_ memory leak — unbindEvt never removed entries from the internal Map. (ce66ba0)
• Duplicate added event — addToDom() fired the event redundantly on every start(). (d94f3bd)
• cleanInactiveTouches spreading native events — prototype properties were lost, producing NaN positions. (d94f3bd)
• Throttle closure leak — Factory resize/scroll handlers created new closures per event, leaking timers Map entries. (d94f3bd)
• trigger() Set mutation — handlers modifying the Set during iteration could skip callbacks. Now snapshots before iterating. (d94f3bd)
• applyPosition zero handling — undefined coordinates were silently treated as 0. (d94f3bd)
• createJoystick crash on invalid position — missing return after error log caused undefined variable access. (d94f3bd)
• Semi mode infinite recursion — added depth guard to processOnStart. (d94f3bd)
• display: 'hidden' invalid CSS — was display instead of visibility. (ce66ba0)

---

🏗️ Infrastructure

• TypeScript throughout — branded types (Uid, Identifier), strict mode, full .d.ts exports
• Yarn 4 monorepo with workspaces: nipplejs, docs, tests, tools, assets
• Rollup bundler — ESM (.mjs) + CJS (.js) + type declarations (.d.ts)
• ESLint flat config + Prettier (e35ca20)
• 196 unit tests (Jest) + 50 e2e tests (Playwright) (291649e, 4235b4d, fc0e27f)
• CI — unit tests, e2e tests, linting, typecheck (including docs) on every PR (e08fed6, c5ce457)
• Release workflow — publish to NPM with OIDC provenance on GitHub release or manual dispatch (e08fed6)
• SSR-safe — window access guarded with typeof checks, removed IE MSPointer dead code (d94f3bd)

---

🌐 Documentation Website

A brand new documentation site built with Astro 6 + Tailwind CSS 4, featuring an "Aurora Neon" dark theme with animated gradient blobs, frosted glass surfaces, and a cursor-following grid highlight.

5 Interactive Game Demos

Each game demo showcases a specific nipplejs option with a live code pane and debug overlay:

Game	Option	Docs
🐍 Neon Snake	mode: 'static'	mode
☄️ Asteroid Dodge	lockX: true	lockX
🎯 Dual-Stick Arena	multitouch	Getting Started
🔭 Space Observatory	follow: true + baseDelta	follow
🚀 Space Drift	restJoystick: false	restJoystick

Carousel with fullscreen mode

Games are displayed in a flex-based horizontal carousel with perspective tilt, blur effects (with Firefox detection fallback), dot indicators, and keyboard/arrow navigation. Each game supports fullscreen mode. (d8defa1, c99bd81)

Mobile optimized

Logo particles and grid highlight disabled on touch devices, game loops paused on non-active carousel slides, simplified transforms. (695bb8a)

GitHub Pages

Auto-deployed on push to master. (011e880)

---

⚠️ Breaking Changes (v0 → v1)

v0	v1
maxNumberOfNipples	maxNumberOfJoysticks
destroyed event	joystickDestroyed
joystick.el	joystick.ui.el
show(), hide(), add(), remove()	Removed
manager.get()	manager.getJoystickByUid() or manager.all
manager.id	manager.uid
manager.ids	Removed
(evt, data) => {}	(evt) => { evt.data }
move fires on direction change only	move fires on every pointermove

See the full migration guide for details.