API Reference

nipplejs exposes three layers: the Collection (Manager) returned by nipplejs.create(), individual Joystick instances, and the singleton Factory for advanced cross-collection coordination.

Collection (Manager)

A Collection is returned when you call nipplejs.create(options). It manages a group of joysticks within a single zone.

Methods

on(type, handler)

Subscribe to events. Supports space-separated event types to bind multiple at once.

const manager = nipplejs.create(options);

manager.on('start', (evt) => {
    console.log('Joystick activated', evt.data.uid);
});

// Multiple events at once
manager.on('start end', (evt) => {
    console.log(evt.type);
});

off([type, handler])

Unsubscribe from events. Called with no arguments, it removes all handlers. With only a type, it removes all handlers for that type. With both, it removes the specific handler.

// Remove a specific handler
manager.off('move', myHandler);

// Remove all 'move' handlers
manager.off('move');

// Remove all handlers
manager.off();

destroy()

Destroy the collection and all its joysticks. Removes DOM elements, unbinds all event listeners, and triggers collectionDestroyed.

manager.destroy();

getJoystickByUid(uid?)

Retrieve a joystick by its unique ID. If no uid is provided, returns the first joystick in the collection.

const joystick = manager.getJoystickByUid(0);

reposition()

Recalculate the zone bounding box and all joystick positions. Call this after the zone element has been moved or when its layout has changed (e.g. entering fullscreen).

The zone is automatically watched with a ResizeObserver, so reposition() is only needed for position changes that don’t involve a resize.

manager.reposition();

Properties

Joystick

Individual joystick instances are accessed through events or via collection.all.

manager.on('move', (evt) => {
    const joystick = evt.data.instance;
    console.log(joystick.uid, joystick.frontPosition);
});

// Or iterate all joysticks
manager.all.forEach((joystick) => {
    console.log(joystick.uid);
});

Methods

on(type, handler)

Subscribe to joystick-level events. Same API as the collection on.

joystick.on('start', (evt) => {
    console.log('This joystick started');
});

off([type, handler])

Unsubscribe from joystick-level events. Same API as the collection off.

destroy()

Destroy this joystick. Removes its DOM elements, clears all timeouts, and triggers joystickDestroyed.

setPosition(cb, {x, y})

Set the front (thumb) position of the joystick programmatically. The position is in pixel coordinates relative to the joystick center. An optional callback fires once the transition completes.

joystick.setPosition(() => {
    console.log('Position set');
}, { x: 20, y: -10 });

Properties

Factory (Advanced)

The factory is a singleton available at nipplejs.factory. It manages all collections and maintains a global index of every joystick across all collections. Most applications will never need to interact with it directly.

import nipplejs from 'nipplejs';

const { factory } = nipplejs;

Methods

getJoystickByUid(uid)

Find a joystick by its uid across all collections. Useful when you have the uid from an event but do not know which collection it belongs to.

const joystick = nipplejs.factory.getJoystickByUid(uid);

getJoystickByIdentifier(identifier)

Find a joystick by the touch/pointer identifier that is currently driving it. This searches across all collections.

const joystick = nipplejs.factory.getJoystickByIdentifier(identifier);

Note: The factory is intended for advanced use cases such as coordinating multiple independent collections (e.g. separate zones for movement and aiming). For most applications, working directly with the collection returned by nipplejs.create() is sufficient.

Logging

Control the library’s console output via setLogLevel.

import nipplejs from 'nipplejs';

nipplejs.setLogLevel('debug');   // all logs (verbose)
nipplejs.setLogLevel('info');    // info, warnings, errors
nipplejs.setLogLevel('warning'); // warnings and errors (default)
nipplejs.setLogLevel('error');   // errors only
nipplejs.setLogLevel('none');    // silent

nipplejs.getLogLevel(); // returns current level