1.2.2 • Public • Published

    Gamepad Icons Module

    Gamepad Icons is an extension to Gamepads.js offering gamepad icons for common gamepad mappings. This package is independant from the main package. See the main package on GitHub or on npm.


    Via npm

    npm install gamepad-icons

    To make the button images available in your app, copy the node_modules/gamepad-icons/buttons folder into a location accessible from your code. See this Stack Overflow answer showing how to configure Webpack to copy the button assets over automatically.

    Then, tell the module where to find the button images:

    import GamepadIcons from 'gamepad-icons';
    GamepadIcons.buttonsPath = 'my/path';

    Alternatively, you can use jsDelivr CDN for accessing button images:

    GamepadIcons.buttonsPath = '';

    Via script tag

    Add the script via jsDelivr or direct download.

    <script src=''></script>

    You can download the full extension, in the Releases tab here. This ZIP archive contains the script and a folder containing the button images. Copy the buttons folder to your project and configure the module to find the images.

    GamepadIcons.buttonsPath = 'my/path';

    Alternatively, you can use jsDelivr CDN for accessing button images:

    GamepadIcons.buttonsPath = '';


    Gamepads.addEventListener('connect', e => {
        console.log('Gamepad connected');
        e.gamepad.addEventListener('buttonpress', e => {
            let button = GamepadIcons.getButton('Xbox One', e.index);

    You must specify one of the following supported mapping names as the first parameter to getButton:

    • "Xbox One"
    • "Xbox 360"
    • "PS4"
    • "PS3"

    The gamepadMappings.getButton function returns an object containing mappingName, buttonName (such as "Y"), and buttonImageSrc, which is the URL for the button's image starting with the default path /buttons. You can change the root path of buttonImageSrc by setting gamepadMappings.buttonsPath.

    Detecting Gamepad Model

    Gamepad objects contain an id property that can offer clues to what brand of gamepad is connected, but you cannot rely on this value because some drivers map gamepads to Xbox 360 layouts for compatibility. Instead, you should give users the option to choose which mapping to display and use their selected mapping in GamepadIcons.getButton calls throughout your application.

    API Reference

    GamepadIconHandler object


    A GamepadIconHandler singleton is exposed as GamepadIcons. This object takes care of querying supported gamepad mappings.


    GamepadIcons.getButton(mappingName, index)

    Gets the given mapping's button at the given index. Returns an object containing mappingName (e.g. 'Xbox One'), buttonName (e.g. 'Y'), and buttonImageSrc.

    You can use the following mappings:

    • Xbox 360
    • Xbox One
    • PS3
    • PS4



    The root path to find button images in. Change this property if you wish to store button image assets somewhere other than as a sibling to gamepad-icons.js. Defaults to /buttons.


    A dictionary of all supported mappings.

    Gamepad Icon Credits

    Gamepad button icon assets courtesy of Nicolae Berbece "Xelu" and are released in the public domain under Creative Commons 0 (CC0).


    npm i gamepad-icons

    DownloadsWeekly Downloads






    Unpacked Size

    256 kB

    Total Files


    Last publish


    • fthompson