> For the complete documentation index, see [llms.txt](https://apps.developer.homey.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apps.developer.homey.app/the-basics/devices/pairing/system-views/devices-list.md).

# Devices List

**Usage:** `"template": "list_devices"`

<figure><img src="/files/HaPu8wXkPeBge99f1Xsl" alt=""><figcaption></figcaption></figure>

{% code title="/drivers/\<driver\_id>/driver.compose.json" %}

```javascript
{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "pair": [
    {
      "id": "list_devices",
      "template": "list_devices",
      "navigation": { "next": "add_devices" },
      "options": { "singular": true }
    },
    {
      "id": "add_devices",
      "template": "add_devices"
    }
  ]
}
```

{% endcode %}

## **Options**

| Key        | Type      | Default | Description                               |
| ---------- | --------- | ------- | ----------------------------------------- |
| `singular` | `boolean` | `false` | Only allow a single device to be selected |

{% tabs %}
{% tab title="JavaScript" %}
{% code title="/drivers/\<driver\_id>/driver.js" %}

```javascript
const Homey = require("homey");
const DeviceApi = require("device-api");

class Driver extends Homey.Driver {
  async onPair(session) {
    session.setHandler("list_devices", async function () {
      const devices = await DeviceApi.discoverDevices();
      
      // you can emit when devices are still being searched
      // session.emit("list_devices", devices);

      // return devices when searching is done
      return devices;

      // when no devices are found, return an empty array
      // return [];

      // or throw an Error to show that instead
      // throw new Error('Something bad has occured!');
    });
  }
}

module.exports = Driver;
```

{% endcode %}

Because the `list_devices` template is very common the [`Driver#onPairListDevices()`](https://apps-sdk-v3.developer.homey.app/Driver.html#onPairListDevices) method exists which you can implement instead of the [`Driver#onPair()`](https://apps-sdk-v3.developer.homey.app/Driver.html#onPair) method.
{% endtab %}

{% tab title="TypeScript" %}
{% code title="/drivers/\<driver\_id>/driver.mts" %}

```mts
import Homey from "homey";
import DeviceApi from "./device-api.mjs";

export default class Driver extends Homey.Driver {
  async onPair(session: Homey.Driver.PairSession): Promise<void> {
    session.setHandler("list_devices", async (): Promise<object[]> => {
      const devices = await DeviceApi.discoverDevices();

      // you can emit when devices are still being searched
      // session.emit("list_devices", devices);

      // return devices when searching is done
      return devices;

      // when no devices are found, return an empty array
      // return [];

      // or throw an Error to show that instead
      // throw new Error('Something bad has occurred!');
    });
  }
}

```

{% endcode %}

Because the `list_devices` template is very common the [`Driver#onPairListDevices()`](https://apps-sdk-v3.developer.homey.app/Driver.html#onPairListDevices) method exists which you can implement instead of the [`Driver#onPair()`](https://apps-sdk-v3.developer.homey.app/Driver.html#onPair) method.
{% endtab %}

{% tab title="Python" %}
{% code title="/drivers/\<driver\_id>/driver.py" %}

```python
from device_api import DeviceApi
from homey import driver
from homey.pair_session import PairSession


class Driver(driver.Driver):
    async def on_pair(self, session: PairSession) -> None:
        async def on_list_device():
            devices = await DeviceApi.discover_devices()

            # you can emit when devices are still being searched
            # session.emit("list_devices", devices);

            # return devices when searching is done
            return devices

            # when no devices are found, return an empty list
            # return []

            # or throw an Error to show that instead
            # raise Exception("Something bad has occurred!")

        session.set_handler("list_devices", on_list_device)


homey_export = Driver

```

{% endcode %}

Because the `list_devices` template is very common the [`Driver#on_pair_list_devices()`](https://python-apps-sdk-v3.developer.homey.app/driver.html#homey.driver.Driver.on_pair_list_devices) method exists which you can implement instead of the [`Driver#on_pair()`](https://python-apps-sdk-v3.developer.homey.app/driver.html#homey.driver.Driver.on_pair) method.
{% endtab %}
{% endtabs %}