This is an alternative site for discovering Elm packages. You may be looking for the official Elm package site instead.
Access to the Gamepad API in pure Elm
version 3.0.0
license MIT
native-modules True
elm-version 0.18.0 <= v < 0.19.0
Tag 3.5.0
Committed At 2017-06-25 20:49:19 UTC
elm-lang/html 2.0.0 <= v < 3.0.0 2.0.0
elm-lang/core 5.1.1 <= v < 6.0.0 5.1.1



:zap: Status: Experimental API, for elm community discussion.


This package provides an Elm language interface for gamepad input.

It works in most modern browsers with both wired and wireless controllers.

Note that to avoid fingerprinting controllers, some browsers only show them after a button has been pressed.

Image of XBox 360 controller

Device and operating system support

I'm developing this on Ubuntu Linux and tested it with:

  • wired USB controllers on Mac OS X, Ubuntu and Centos
  • Bluetooth controllers on Android (in Firefox)

It works out of the box on Linux and Android, and probably Windows.

On Mac OS X you may need to install a driver, such as XBox 360 controller driver for OSX.

Elm interface

A StandardGamepad is a record with named fields for buttons and thumbsticks.


A Button represents the current state of an analog or digital button or trigger. According to the spec:

All button values must be linearly normalized to the range [0.0 .. 1.0]. 0.0 must mean fully unpressed, and 1.0 must mean fully pressed. For buttons without an analog sensor, only the values 0.0 and 1.0 for fully unpressed and fully pressed must be provided.

type alias Button =
  { pressed : Bool
  , value : Float


A Stick represents a thumbstick with two analog axes x and y, and a Button for pressing down on the stick.

All axis values must be linearly normalized to the range [-1.0 .. 1.0]. As appropriate, -1.0 should correspond to "up" or "left", and 1.0 should correspond to "down" or "right".

type alias Stick =
    { x : Float
    , y : Float
    , button : Button


Most controllers are converted to StandardGamepad by your browser and elm-gamepad.

Image of StandardGamepad mapping

type Gamepad =
      StandardGamepad StandardGamepad_
    | RawGamepad RawGamepad_

type alias StandardGamepad_ =
    { id : String

   , buttonBack   : Button
   , buttonStart  : Button
   , buttonLogo   : Button

   , buttonA : Button
   , buttonB : Button
   , buttonX : Button
   , buttonY : Button

   , leftTrigger    : Button
   , leftBumper     : Button
   , leftStick      : Stick

   , rightTrigger    : Button
   , rightBumper     : Button
   , rightStick      : Stick

   , dPadUp    : Button
   , dPadDown  : Button
   , dPadLeft  : Button
   , dPadRight : Button


If a controller is unknown it will appear as a RawGamepad.

RawGamepad is the underlying HTML5 Gamepad representation, containing lists of Buttons, and floats for the axes.

Axis values are listed in pairs, X followed by Y.

type alias RawGamepad_ =
   { id : String
   , axes : List Float
   , buttons : List Button
   , mapping : String

If your gamepad shows as RawGamepad, it is useful to write a function to convert it to StandardGamepad. I'll gladly accept patches to src/Internal/Convert.elm to add support for unknown gamepads, so that other users with your model of gamepad can play Elm games.