Nanoleaf Integration Setup

Nanoleaf products connect to Home Assistant in two different ways depending on the product line. Light panels (Shapes, Canvas, Elements, and Lines) use Nanoleaf’s local TCP API through the built-in Nanoleaf integration. Essentials bulbs and strips connect over Thread or Matter instead and do not use the Nanoleaf integration at all.

Before You Start

Confirm the following before you begin:

1. Your Nanoleaf devices are powered on and set up in the Nanoleaf app.
2. For light panels: the panels are on the same LAN as Home Assistant and visible in the Nanoleaf app.
3. For Essentials over Thread or Matter: your Thread network and Matter integration are set up. See the Matter and Thread Protocol Setup guide.

Set Up Light Panels (Shapes, Canvas, Elements, and Lines)

1. Make sure the panels are on your LAN and visible in the Nanoleaf app.
2. In Home Assistant, go to Settings > Devices & Services > Add Integration and search for Nanoleaf.
3. When asked for a Host, enter either:
   • the Nanoleaf’s IP address (most reliable; find it in your router’s DHCP table), or
   • its hostname, if you know it resolves correctly.
4. Home Assistant shows a prompt like “Press the power button for 5 seconds and click Submit within 30s.” This puts the controller into pairing mode so Home Assistant can obtain an API token.
5. Once paired, you get a light entity plus events for gestures, depending on the model.

Set Up Essentials Bulbs and Strips (Thread and Matter)

Essentials devices are exposed through the HomeKit Controller integration (if they are HomeKit-only over Thread or Bluetooth) or the Matter integration (if they are Matter over Thread). There are two common paths.

Option 1: Move from Apple Home via HomeKit Controller

1. Add the bulb in Apple Home and let it join your Thread network.
2. Remove it from Apple Home but keep it powered.
3. The device should then appear in Home Assistant via HomeKit Controller, where you pair it again using its HomeKit code.

Option 2: Share from Apple Home via Matter

1. Set up the bulb in Apple Home as a Matter device.
2. In Apple Home, open Accessory Settings, select Turn on Pairing Mode, and copy the new pairing code.
3. In the Home Assistant iOS app, go to Settings > Devices > Add Integration > Matter, select More options, then My accessory isn’t shown here, then Enter code, and paste the code.