Skip to main content
The light platform allows integrations to control lighting devices with support for brightness, color, effects, and more.

​
Base Class

All light entities inherit from LightEntity, which extends ToggleEntity. The class is defined in homeassistant.components.light. 
from homeassistant.components.light import LightEntity

class MyLight(LightEntity):
    """Representation of a light."""

​
Color Modes

Lights must declare which color modes they support. This is the most important configuration: 
from homeassistant.components.light import ColorMode

class MyLight(LightEntity):
    """A light with color support."""

    _attr_supported_color_modes = {ColorMode.RGB}
Available color modes:
  • ONOFF - Simple on/off
  • BRIGHTNESS - Brightness control only
  • COLOR_TEMP - Color temperature (white spectrum)
  • HS - Hue/Saturation
  • RGB - RGB color
  • RGBW - RGB + White channel
  • RGBWW - RGB + Warm White + Cool White
  • WHITE - White channel brightness
  • XY - CIE 1931 color space

​
Required Properties

​
supported_color_modes

Set of color modes the light supports. 
@cached_property
def supported_color_modes(self) -> set[ColorMode] | None:
    """Flag supported color modes."""
    return self._attr_supported_color_modes

​
color_mode

The current active color mode. 
@cached_property
def color_mode(self) -> ColorMode | None:
    """Return the color mode of the light."""
    return self._attr_color_mode

​
Required Methods

​
turn_on

Turn the light on with optional parameters. 
async def async_turn_on(self, **kwargs: Any) -> None:
    """Turn the light on."""
    # Handle brightness, color, etc. from kwargs
    if ATTR_BRIGHTNESS in kwargs:
        brightness = kwargs[ATTR_BRIGHTNESS]
        # Set brightness (0-255)

​
turn_off

Turn the light off. 
async def async_turn_off(self, **kwargs: Any) -> None:
    """Turn the light off."""
    # Turn off the light

​
Optional Properties

​
brightness

Current brightness (0-255). Required for brightness-capable lights. 
@cached_property
def brightness(self) -> int | None:
    """Return the brightness of this light between 0..255."""
    return self._attr_brightness

​
rgb_color

Current RGB color as tuple (r, g, b) where each value is 0-255. 
@cached_property
def rgb_color(self) -> tuple[int, int, int] | None:
    """Return the rgb color value [int, int, int]."""
    return self._attr_rgb_color

​
hs_color

Current hue/saturation as tuple (hue, saturation) where hue is 0-360 and saturation is 0-100. 
@cached_property
def hs_color(self) -> tuple[float, float] | None:
    """Return the hue and saturation color value [float, float]."""
    return self._attr_hs_color

​
color_temp_kelvin

Current color temperature in Kelvin. 
@property
def color_temp_kelvin(self) -> int | None:
    """Return the CT color value in Kelvin."""
    return self._attr_color_temp_kelvin

​
min_color_temp_kelvin / max_color_temp_kelvin

Temperature range for color temperature lights. 
@property
def min_color_temp_kelvin(self) -> int:
    """Return the warmest color_temp_kelvin that this light supports."""
    return self._attr_min_color_temp_kelvin

@property
def max_color_temp_kelvin(self) -> int:
    """Return the coldest color_temp_kelvin that this light supports."""
    return self._attr_max_color_temp_kelvin

​
effect_list

List of available effects. 
@cached_property
def effect_list(self) -> list[str] | None:
    """Return the list of supported effects."""
    return self._attr_effect_list

​
effect

Current effect. 
@cached_property
def effect(self) -> str | None:
    """Return the current effect."""
    return self._attr_effect

​
supported_features

Additional features beyond color modes. 
@cached_property
def supported_features(self) -> LightEntityFeature:
    """Flag supported features."""
    return self._attr_supported_features
Available features:
  • EFFECT - Supports effects
  • FLASH - Supports flashing
  • TRANSITION - Supports transition time

​
Example Implementations

​
Simple Dimmable Light

from homeassistant.components.light import (
    ATTR_BRIGHTNESS,
    ColorMode,
    LightEntity,
)

class DimmableLight(LightEntity):
    """A dimmable light."""

    _attr_supported_color_modes = {ColorMode.BRIGHTNESS}
    _attr_color_mode = ColorMode.BRIGHTNESS

    def __init__(self) -> None:
        """Initialize the light."""
        self._attr_is_on = False
        self._attr_brightness = 255

    async def async_turn_on(self, **kwargs: Any) -> None:
        """Turn the light on."""
        if ATTR_BRIGHTNESS in kwargs:
            self._attr_brightness = kwargs[ATTR_BRIGHTNESS]
        
        await self._device.set_brightness(self._attr_brightness)
        self._attr_is_on = True
        self.async_write_ha_state()

    async def async_turn_off(self, **kwargs: Any) -> None:
        """Turn the light off."""
        await self._device.turn_off()
        self._attr_is_on = False
        self.async_write_ha_state()

​
RGB Color Light

from homeassistant.components.light import (
    ATTR_BRIGHTNESS,
    ATTR_RGB_COLOR,
    ColorMode,
    LightEntity,
)

class RGBLight(LightEntity):
    """An RGB color light."""

    _attr_supported_color_modes = {ColorMode.RGB}
    _attr_color_mode = ColorMode.RGB

    def __init__(self) -> None:
        """Initialize the light."""
        self._attr_is_on = False
        self._attr_brightness = 255
        self._attr_rgb_color = (255, 255, 255)

    async def async_turn_on(self, **kwargs: Any) -> None:
        """Turn the light on."""
        if ATTR_BRIGHTNESS in kwargs:
            self._attr_brightness = kwargs[ATTR_BRIGHTNESS]
        
        if ATTR_RGB_COLOR in kwargs:
            self._attr_rgb_color = kwargs[ATTR_RGB_COLOR]
        
        await self._device.set_rgb(
            self._attr_rgb_color[0],
            self._attr_rgb_color[1],
            self._attr_rgb_color[2],
            self._attr_brightness,
        )
        self._attr_is_on = True
        self.async_write_ha_state()

    async def async_turn_off(self, **kwargs: Any) -> None:
        """Turn the light off."""
        await self._device.turn_off()
        self._attr_is_on = False
        self.async_write_ha_state()

​
Color Temperature Light

from homeassistant.components.light import (
    ATTR_BRIGHTNESS,
    ATTR_COLOR_TEMP_KELVIN,
    ColorMode,
    LightEntity,
)

class ColorTempLight(LightEntity):
    """A color temperature light."""

    _attr_supported_color_modes = {ColorMode.COLOR_TEMP}
    _attr_color_mode = ColorMode.COLOR_TEMP
    _attr_min_color_temp_kelvin = 2000
    _attr_max_color_temp_kelvin = 6500

    def __init__(self) -> None:
        """Initialize the light."""
        self._attr_is_on = False
        self._attr_brightness = 255
        self._attr_color_temp_kelvin = 4000

    async def async_turn_on(self, **kwargs: Any) -> None:
        """Turn the light on."""
        if ATTR_BRIGHTNESS in kwargs:
            self._attr_brightness = kwargs[ATTR_BRIGHTNESS]
        
        if ATTR_COLOR_TEMP_KELVIN in kwargs:
            self._attr_color_temp_kelvin = kwargs[ATTR_COLOR_TEMP_KELVIN]
        
        await self._device.set_color_temp(
            self._attr_color_temp_kelvin,
            self._attr_brightness,
        )
        self._attr_is_on = True
        self.async_write_ha_state()

    async def async_turn_off(self, **kwargs: Any) -> None:
        """Turn the light off."""
        await self._device.turn_off()
        self._attr_is_on = False
        self.async_write_ha_state()

​
Light with Effects

from homeassistant.components.light import (
    ATTR_EFFECT,
    ColorMode,
    LightEntity,
    LightEntityFeature,
)

class EffectLight(LightEntity):
    """A light with effects."""

    _attr_supported_color_modes = {ColorMode.RGB}
    _attr_color_mode = ColorMode.RGB
    _attr_supported_features = LightEntityFeature.EFFECT
    _attr_effect_list = ["rainbow", "pulse", "strobe"]

    def __init__(self) -> None:
        """Initialize the light."""
        self._attr_is_on = False
        self._attr_effect = None

    async def async_turn_on(self, **kwargs: Any) -> None:
        """Turn the light on."""
        if ATTR_EFFECT in kwargs:
            self._attr_effect = kwargs[ATTR_EFFECT]
            await self._device.set_effect(self._attr_effect)
        
        self._attr_is_on = True
        self.async_write_ha_state()

​
Turn On Parameters

The turn_on method can receive these parameters:
  • ATTR_BRIGHTNESS - Brightness (0-255)
  • ATTR_BRIGHTNESS_PCT - Brightness percentage (0-100)
  • ATTR_BRIGHTNESS_STEP - Relative brightness step (-255 to 255)
  • ATTR_BRIGHTNESS_STEP_PCT - Relative brightness step percentage (-100 to 100)
  • ATTR_RGB_COLOR - RGB color tuple (r, g, b)
  • ATTR_RGBW_COLOR - RGBW color tuple (r, g, b, w)
  • ATTR_RGBWW_COLOR - RGBWW color tuple (r, g, b, cw, ww)
  • ATTR_HS_COLOR - Hue/Saturation tuple (hue, saturation)
  • ATTR_XY_COLOR - XY color tuple (x, y)
  • ATTR_COLOR_TEMP_KELVIN - Color temperature in Kelvin
  • ATTR_WHITE - White level (0-255)
  • ATTR_EFFECT - Effect name
  • ATTR_FLASH - Flash (“short” or “long”)
  • ATTR_TRANSITION - Transition time in seconds

​
Important Notes

  • Always set supported_color_modes - it’s required
  • Set color_mode to the current active mode when the light is on
  • Home Assistant automatically converts between color representations
  • Only implement the properties for your supported color modes
  • Use async_write_ha_state() to update Home Assistant after state changes
  • The light platform handles color conversions automatically

​
Color Mode Combinations

Valid combinations of color modes:
  • Single mode: {ColorMode.RGB}
  • Multiple modes: {ColorMode.RGB, ColorMode.COLOR_TEMP}
  • The ONOFF and BRIGHTNESS modes are automatically filtered if other modes exist

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us