use-gamepad

Button indices of the W3C "standard" gamepad mapping.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useGamepad, mapGamepad, snapshotGamepad, standardGamepadButtons, standardGamepadAxes } from "@vizejs/composable/use-gamepad";

Try it

Show connected controllers

Poll connected game controllers and show which buttons are pressed.

Open the interactive example

What to observe: Connect a controller and press a button; it appears with the number of pressed buttons.

Browsers only report a gamepad after a button press. Polling runs on animation frames while the component is mounted. Every example renders a neutral message until it mounts, so server and client markup match, and then explains what to do when the browser lacks the API.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useGamepad } from "@vizejs/composable/use-gamepad";
import { useMounted } from "@vizejs/composable/use-mounted";

const mounted = useMounted();
const { supported, gamepads } = useGamepad();
</script>

<template>
  <div class="composable-example">
    <p>Show connected game controllers and which buttons are pressed.</p>
    <ul aria-label="Controllers">
      <li v-for="pad in gamepads" :key="pad.index">
        {{ pad.id }}: {{ pad.buttons.filter((button) => button.pressed).length }} buttons pressed
      </li>
    </ul>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : !supported
          ? "The Gamepad API is not available in this browser."
          : gamepads.length === 0
            ? "Connect a controller and press any button."
            : `${gamepads.length} controllers connected.`
    }}</output>
  </div>
</template>

Runtime contract

API

standardGamepadButtons

Button indices of the W3C "standard" gamepad mapping.

const standardGamepadButtons

standardGamepadAxes

Axis indices of the W3C "standard" gamepad mapping.

const standardGamepadAxes

snapshotGamepad

Copy a live pad into an immutable GamepadSnapshot.

function snapshotGamepad(pad: GamepadLike): GamepadSnapshot

mapGamepad

Derive typed named state from a snapshot. Missing buttons read as released and missing axes as 0; axis dead zones are applied and rescaled.

function mapGamepad<const Mapping extends GamepadMapping>( snapshot: Pick<GamepadSnapshot, "buttons" | "axes">, mapping: Mapping, ): MappedGamepad<Mapping>

const state = mapGamepad(pad, { jump: { button: 0 }, moveX: { axis: 0, deadzone: 0.1 } });
state.jump.pressed; state.moveX; // boolean, number

useGamepad

Track connected gamepads as immutable snapshots, polled on animation frames, with optional typed named bindings. Pads are re-read every frame while active and on gamepadconnected / gamepaddisconnected; gamepads is replaced only when a pad's timestamp or connection changed. Entries are plain copies, so they are safe to keep or serialize. The frame loop and listeners stop with the owning reactive scope; outside a scope call pause(). Server rendering: no frames or listeners, supported is false and gamepads is empty. Inside a component the host is resolved after mounting, so hydration renders this server state first.

function useGamepad<const Mapping extends GamepadMapping = Record<never, never>>( options: UseGamepadOptions<Mapping> = {}, ): GamepadControls<Mapping>

const { gamepads } = useGamepad({ mapping: { jump: { button: 0 }, moveX: { axis: 0, deadzone: 0.1 } } });
const player = computed(() => gamepads.value[0]?.mapped);

Types

GamepadButtonLike

Minimal GamepadButton read by useGamepad.

GamepadVibrationActuatorLike

Minimal GamepadHapticActuator used for vibration.

GamepadLike

Minimal live Gamepad object read by useGamepad.

GamepadHost

Window-like capability used by useGamepad.

GamepadVibrationParams

Parameters of a dual-rumble vibration effect.

GamepadButtonState

Plain, copied state of one button.

GamepadSnapshot

Immutable copy of a pad taken at one poll; never a live Gamepad.

GamepadButtonBinding

Binds a mapping key to a button; the mapped value is a GamepadButtonState.

GamepadAxisBinding

Binds a mapping key to an axis; the mapped value is a number.

ConnectedGamepad

One connected pad: its snapshot plus the mapped state.

UseGamepadOptions

Options for useGamepad.

GamepadControls

Reactive state and actions returned by useGamepad.