Gamepad UI Engine (gamepad-controller)

Description

Gamepad UI Engine is a browser library for controller-driven UI navigation. It supports spatial, grid, and horizontal layouts in vanilla JavaScript/TypeScript, React, and Angular, plus custom-event input from a host. The npm package is gamepad-ui-engine; its source repository is gamepad-controller.

Live Demo

Explore the GitHub Pages demo and documentation, including interactive examples.

Installation

Install the published package from npm:

npm install gamepad-ui-engine

For a browser page without a bundler, import the versioned ESM build from a CDN in a module script:

<script type="module">
  import { GamepadService } from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/index.js';
  // Create the service after the navigation elements exist.
</script>

The package is ESM only; the CDN URL is a module import, not a classic script with a global variable. Version 1.0.0 was the first published release. To try unreleased changes, build and install a local tarball.

Quick Start

Add a container with focusable elements:

<main id="catalog">
  <button>Play</button>
  <button>Library</button>
</main>

Initialize the service after that HTML is rendered, and destroy it when the view is removed:

import { GamepadService } from 'gamepad-ui-engine';

const service = new GamepadService({
  containerSelector: '#catalog',
  navigationMode: 'spatial',
  autoAddStyles: true,
});

service.init();
// When removing this view: service.destroy();

API Usage

GamepadService owns an instance's input and focus lifecycle. Subscribe with service.on(event, listener) before init() when you need controller or navigation events; the returned function removes that listener. Use service.refresh() after changing navigation elements, and call service.destroy() when the owning view is removed. See the public API reference and configuration guide for methods, events, and options.

Documentation

• Package guide
• Project cookbook: websites, small apps, landing pages, and mini games
• Vanilla JavaScript / TypeScript, React, Angular
• Public API and architecture
• Building and packaging
• First-release notes
• AI consumer skills
• Contributing

Library guides live in docs/. Portable AI skill folders remain self-contained in skills/.

• Complete configuration
• Complete public contracts