Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/esphome/esphome.io/llms.txt

Use this file to discover all available pages before exploring further.

ESPHome’s light domain transforms GPIO outputs, PWM channels, and addressable LED drivers into full-featured Home Assistant light entities. A single configuration block covers everything from a simple on/off LED to a 300-pixel RGBWW NeoPixel strip with animated effects, color temperature control, gamma correction, and persistent state across reboots.

​
Base Light Configuration

All light platforms share these configuration variables. 
light:
  - platform: neopixelbus
    type: GRB
    variant: WS2812
    pin: GPIO16
    num_leds: 60
    name: "Living Room Strip"
    restore_mode: RESTORE_DEFAULT_OFF
    default_transition_length: 1s
    gamma_correct: 2.8
    effects:
      - pulse:
      - addressable_rainbow:
      - addressable_twinkle:
​
id
string
Manually specify the ID for code generation. At least one of id and name must be specified.
​
name
string
The name of the light in Home Assistant. Set to None to inherit the device’s friendly_name.
​
icon
icon
Manually override the MDI icon shown in the frontend.
​
restore_mode
enum
How the light restores state on boot:
  • ALWAYS_OFF (default) — always start off.
  • ALWAYS_ON — always start on.
  • RESTORE_DEFAULT_OFF — restore last state, default to off.
  • RESTORE_DEFAULT_ON — restore last state, default to on.
  • RESTORE_AND_OFF / RESTORE_AND_ON — restore colors but force on/off state.
  • RESTORE_INVERTED_DEFAULT_OFF / RESTORE_INVERTED_DEFAULT_ON — invert restored state.
​
gamma_correct
float
Gamma correction factor applied to all channels. Defaults to 2.8. Set to 1.0 to disable.
​
default_transition_length
Time
Default transition time when no explicit length is specified. Defaults to 1s.
​
flash_transition_length
Time
Transition length used during flash calls. Defaults to 0s.
​
effects
list
A list of light effects to make available. Each entry in this list appears as an effect option in Home Assistant.
​
color_correct
list of float
Per-channel maximum brightness correction for addressable lights, e.g. [100%, 50%, 100%].
​
power_supply
ID
ID of a power_supply component to automatically switch on when the light turns on.
​
disabled_by_default
boolean
If true, the entity is hidden in Home Assistant until manually enabled. Defaults to false.

​
Light Automations

​
light.turn_on Action

on_...:
  - light.turn_on:
      id: my_light
      brightness: 80%
      red: 100%
      green: 0%
      blue: 0%
      transition_length: 500ms
  # Shorthand:
  - light.turn_on: my_light

​
light.turn_off Action

on_...:
  - light.turn_off:
      id: my_light
      transition_length: 1s

​
light.toggle Action

on_...:
  - light.toggle: my_light

​
light.dim_relative Action

Increase or decrease brightness by a relative percentage — great for button hold-to-dim. 
on_...:
  - light.dim_relative:
      id: my_light
      relative_brightness: 5%
      transition_length: 0.1s
      brightness_limits:
        min_brightness: 5%
        max_brightness: 100%

​
light.addressable_set Action

Set individual LEDs on an addressable strip. 
on_...:
  - light.addressable_set:
      id: my_strip
      range_from: 0
      range_to: 9
      red: 100%
      green: 0%
      blue: 0%

​
Triggers

light:
  - platform: ...
    on_turn_on:
      - logger.log: "Light turned on"
    on_turn_off:
      - logger.log: "Light turned off"
    on_state:
      - logger.log: "Light state changed"

​
light.is_on / light.is_off Condition

on_...:
  if:
    condition:
      light.is_on: my_light
    then:
      - light.turn_off: my_light

​
Light Effects

ESPHome has many built-in effects. List the ones you want in the effects: key; each appears as a selectable effect in Home Assistant.

​
Pulse

Smoothly fades in and out. 
effects:
  - pulse:
      name: "Slow Pulse"
      transition_length: 1s
      update_interval: 2s
      min_brightness: 0%
      max_brightness: 100%

​
Random

Transitions to a randomly chosen color at each interval. 
effects:
  - random:
      name: "Color Random"
      transition_length: 5s
      update_interval: 7s

​
Strobe

Cycles through a list of colors with defined durations. 
effects:
  - strobe:
      name: "Red Blue Strobe"
      colors:
        - state: true
          red: 100%
          green: 0%
          blue: 0%
          duration: 200ms
        - state: true
          red: 0%
          green: 0%
          blue: 100%
          duration: 200ms

​
Flicker

Simulates a candle flame by randomly varying brightness and color. 
effects:
  - flicker:
      alpha: 95%
      intensity: 1.5%

​
Addressable Effects (NeoPixel / addressable strips only)

effects:
  - addressable_rainbow:
      speed: 10
      width: 50
  - addressable_color_wipe:
      add_led_interval: 100ms
      reverse: false
  - addressable_scan:
      move_interval: 100ms
      scan_width: 1
  - addressable_twinkle:
      twinkle_probability: 5%
      progress_interval: 4ms
  - addressable_random_twinkle:
  - addressable_fireworks:
      spark_probability: 10%
      fade_out_rate: 120
  - addressable_flicker:
      intensity: 5%

​
WLED Effect

Receive realtime UDP control from WLED-compatible software (Prismatik, LedFx, Hyperion). 
wled:

light:
  - platform: neopixelbus
    effects:
      - wled:
          port: 21324

​
E1.31 Effect

Receive DMX-over-UDP from JINX, Hyperion.NG, and similar lighting control software. 
e131:
  method: multicast

light:
  - platform: neopixelbus
    num_leds: 189
    effects:
      - e131:
          universe: 1
          channels: RGB

Binary Light

Simple on/off control using a binary output. The most basic light type.

Monochromatic Light

Single-channel brightness control using a float (PWM) output.

RGB Light

Three PWM outputs for red, green, and blue channels. Full color control.

RGBW / RGBWW Light

RGB plus separate white (and warm white) channels. Supports color temperature control.

NeoPixelBus

Addressable LED strips (WS2812, SK6812, APA102, etc.) via the NeoPixelBus library.

FastLED

Alternative addressable LED driver using the FastLED library. Supports many strip types.

Partition

Split one addressable strip into independently controlled segments.

Color Temperature

Cold/warm white dual-channel light with Home Assistant color temperature control.

Build docs developers (and LLMs) love

Get started for freeTalk to us