Light Platform

API reference for implementing light entities in Home Assistant

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

• Entity Documentation
• Color Utilities
• Light Constants
• Demo Light Implementation