1---
2category: Browser
3---
4 
5# useGamepad
6 
7Provides reactive bindings for the [Gamepad API](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API).
8 
9## Usage
10 
11> Due to how the Gamepad API works, you must interact with the page using the gamepad before it will be detected.
12 
13```vue
14<script setup lang="ts">
15import { useGamepad } from '@vueuse/core'
16import { computed } from 'vue'
17 
18const { isSupported, gamepads } = useGamepad()
19const gamepad = computed(() => gamepads.value.find(g => g.mapping === 'standard'))
20</script>
21 
22<template>
23  <span>
24    {{ gamepad.id }}
25  </span>
26</template>
27```
28 
29### Gamepad Updates
30 
31Currently the Gamepad API does not have event support to update the state of the gamepad. To update the gamepad state, `requestAnimationFrame` is used to poll for gamepad changes. You can control this polling by using the `pause` and `resume` functions provided by `useGamepad`
32 
33```ts
34import { useGamepad } from '@vueuse/core'
35 
36const { pause, resume, gamepads } = useGamepad()
37 
38pause()
39 
40// gamepads object will not update
41 
42resume()
43 
44// gamepads object will update on user input
45```
46 
47### Gamepad Connect & Disconnect Events
48 
49The `onConnected` and `onDisconnected` events will trigger when a gamepad is connected or disconnected.
50 
51```ts
52import { useGamepad } from '@vueuse/core'
53// ---cut---
54const { gamepads, onConnected, onDisconnected } = useGamepad()
55 
56onConnected((index) => {
57  console.log(`${gamepads.value[index].id} connected`)
58})
59 
60onDisconnected((index) => {
61  console.log(`${index} disconnected`)
62})
63```
64 
65### Vibration
66 
67> The Gamepad Haptics API is sparse, so check the [compatibility table](https://developer.mozilla.org/en-US/docs/Web/API/GamepadHapticActuator#browser_compatibility) before using.
68 
69<!-- eslint-disable import/first -->
70 
71```ts
72import { useGamepad } from '@vueuse/core'
73 
74const { gamepads, onConnected, onDisconnected } = useGamepad()
75const gamepad = gamepads.value[0]!
76// ---cut---
77import { computed } from 'vue'
78 
79const supportsVibration = computed(() => gamepad.hapticActuators.length > 0)
80function vibrate() {
81  if (supportsVibration.value) {
82    const actuator = gamepad.hapticActuators[0]
83    actuator.playEffect('dual-rumble', {
84      startDelay: 0,
85      duration: 1000,
86      weakMagnitude: 1,
87      strongMagnitude: 1,
88    })
89  }
90}
91```
92 
93### Mappings
94 
95To make the Gamepad API easier to use, we provide mappings to map a controller to a controllers button layout.
96 
97#### Xbox360 Controller
98 
99```vue
100<script setup>
101import { mapGamepadToXbox360Controller } from '@vueuse/core'
102 
103const controller = mapGamepadToXbox360Controller(gamepad)
104</script>
105 
106<template>
107  <span>{{ controller.buttons.a.pressed }}</span>
108  <span>{{ controller.buttons.b.pressed }}</span>
109  <span>{{ controller.buttons.x.pressed }}</span>
110  <span>{{ controller.buttons.y.pressed }}</span>
111</template>
112```
113 
114Currently there are only mappings for the Xbox 360 controller. If you have controller you want to add mappings for, feel free to open a PR for more controller mappings!
115 
116### SSR Compatibility
117 
118This component is designed to be used in the client side. In some cases, SSR might cause some hydration mismatches.
119 
120If you are using Nuxt, you can simply rename your component file with the `.client.vue` suffix (e.g., `GamepadComponent.client.vue`) which will automatically make it render only on the client side, avoiding hydration mismatches.
121 
122In other frameworks or plain Vue, you can wrap your usage component with a `<ClientOnly>` component to ensure it is only rendered on the client side.
123 
124## Type Declarations
125 
126```ts
127export interface UseGamepadOptions
128  extends ConfigurableWindow, ConfigurableNavigator {}
129export interface UseGamepadReturn extends Supportable, Pausable {
130  onConnected: EventHookOn<number>
131  onDisconnected: EventHookOn<number>
132  gamepads: Ref<Gamepad[]>
133}
134/**
135 * Maps a standard standard gamepad to an Xbox 360 Controller.
136 */
137export declare function mapGamepadToXbox360Controller(
138  gamepad: Ref<Gamepad | undefined>,
139): ComputedRef<{
140  buttons: {
141    a: GamepadButton
142    b: GamepadButton
143    x: GamepadButton
144    y: GamepadButton
145  }
146  bumper: {
147    left: GamepadButton
148    right: GamepadButton
149  }
150  triggers: {
151    left: GamepadButton
152    right: GamepadButton
153  }
154  stick: {
155    left: {
156      horizontal: number
157      vertical: number
158      button: GamepadButton
159    }
160    right: {
161      horizontal: number
162      vertical: number
163      button: GamepadButton
164    }
165  }
166  dpad: {
167    up: GamepadButton
168    down: GamepadButton
169    left: GamepadButton
170    right: GamepadButton
171  }
172  back: GamepadButton
173  start: GamepadButton
174} | null>
175export declare function useGamepad(
176  options?: UseGamepadOptions,
177): UseGamepadReturn
178```
179