> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

```python theme={null}
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:

```python theme={null}
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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@cached_property
def effect_list(self) -> list[str] | None:
    """Return the list of supported effects."""
    return self._attr_effect_list
```

### effect

Current effect.

```python theme={null}
@cached_property
def effect(self) -> str | None:
    """Return the current effect."""
    return self._attr_effect
```

### supported\_features

Additional features beyond color modes.

```python theme={null}
@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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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](/api/entity)
* [Color Utilities](https://github.com/home-assistant/core/blob/dev/homeassistant/util/color.py)
* [Light Constants](https://github.com/home-assistant/core/blob/dev/homeassistant/components/light/const.py)
* [Demo Light Implementation](https://github.com/home-assistant/core/blob/dev/homeassistant/components/demo/light.py)