Relative Light Group

A custom Home Assistant integration that creates light groups with relative brightness control. This integration is built upon the codebase of the official Home Assistant group integration, extending its native functionality.

Unlike standard light groups, this integration maintains the relative brightness ratio between lights when adjusting the group brightness. Changes to color, effects, and other attributes are only applied to lights that are currently on — off lights are never accidentally turned on by attribute changes.

Features

• Relative Brightness — When you change the group brightness, each on-light's brightness is adjusted proportionally. Brighter lights stay brighter, dimmer lights stay dimmer.
• Only-On-Lights — Color, effect, color temperature, and other visual attribute changes are only sent to lights that are currently on. Off lights remain off.
• Remember on/off state — If enabled, when the group is turned off and on again, only the lights that were previously on will turn on.
• Restore individual brightness — If enabled, when you turn the group off and on again from the group entity, each light that turns on is set to the brightness it had before the group was turned off. On/off-only lights turn on as usual. If you turn the group on with an explicit brightness, that value is used for all targets instead.
• Maintain relative brightness — If enabled, the group keeps brightness ratios between lights. Proportions are preserved even when the group reaches minimum or maximum brightness. Individual brightness can only be changed directly on each light, not from the group.
• Optimistic State Debounce — Prevents UI "bouncing" (slider jumping) by ignoring member state updates for a short period after a group command is sent.
• Configurable Debounce Time — Adjust the debounce window (default 2000ms) to match your network's latency.
• Native Group Features — Supports the same standard options as the native integration: selecting light entities, "All entities must be on", and "Hide members".
• Config Flow UI — Create and configure groups entirely through the Home Assistant UI (Settings → Helpers).
• Multi-language — Localized in English, Spanish, German, French, Italian, and Portuguese.

Installation

HACS (Recommended)

1. Open HACS in your Home Assistant instance
2. Go to Integrations
3. Click the three dots menu (⋮) → Custom repositories
4. Add this repository URL and select Integration as the category
5. Search for "Relative Light Group" and install it
6. Restart Home Assistant

Manual

1. Copy the custom_components/relative_light_group folder to your Home Assistant config/custom_components/ directory
2. Restart Home Assistant

Configuration

1. Go to Settings → Devices & Services → Helpers
2. Click + Create Helper
3. Select Relative Light Group
4. Enter a name, select your light entities, and configure options
5. Click Submit

Options

This integration supports the same standard options as the native group integration (Light entities, All entities must be on, and Hide members). In addition, it provides the following custom options:

Option	Description
Remember on/off state	If enabled, when the group is turned off and on again, only the lights that were previously on will turn on.
Restore individual brightness	If enabled, when you turn the group off and on again from the group entity, each light that turns on is set to the brightness it had before the group was turned off. On/off-only lights turn on as usual. If you turn the group on with an explicit brightness, that value is used for all targets instead.
Maintain relative brightness	If enabled, the group keeps brightness ratios between lights. Proportions are preserved even when the group reaches minimum or maximum brightness. Individual brightness can only be changed directly on each light, not from the group.
Enable optimistic state debounce	If enabled, the group ignores state updates from members for a short period after a command is sent, preventing the UI slider from jumping.
Debounce time	The amount of time in milliseconds to ignore member state updates (default 2000ms).

How Relative Brightness Works

When you adjust the group brightness slider:

1. The integration calculates the brightness change as a ratio
2. Each on-light receives a proportional adjustment based on its current brightness
3. Brighter lights get a larger absolute change, dimmer lights get a smaller change
4. The relative ratios between lights are maintained

Example: Group has Light A at 200/255 and Light B at 100/255. If you increase the group to maximum:

• Light A (closer to max) increases to 255
• Light B increases proportionally, maintaining its relative position

Services

The integration registers four services under the relative_light_group domain. They are fully compatible with the Developer Tools service UI (selectors with native pickers) and can be called from automations, scripts, scenes, or buttons. All services target one or more group entities (entities of light domain that belong to this integration); the matching config entries are reloaded after a successful change.

Common rules:

• The target entity must belong to a loaded Relative Light Group. Any other targets are skipped (and the call fails if none of the targeted entities is a valid group).
• Membership changes never allow nesting: any light that itself belongs to another Relative Light Group is rejected to prevent circular references. The same rule is enforced when creating or editing a group from the UI.
• A group cannot be left empty.
• All membership operations deduplicate while preserving the order you provided.
• Calls are serialized per group (an internal lock per config entry) to avoid races between concurrent automations.

relative_light_group.set_options

Friendly name: Update group options

Update one or more options of a Relative Light Group. Only the keys you send are changed; the rest are preserved. The group is reloaded after a successful change.

Target: one or more light entities of this integration.

Field	Friendly name	Description	Type / domain	Default	Required
all	All entities must be on	Group is considered on only when all members are on. If false, on when any member is on.	boolean	false (existing value preserved if not sent)	No
hide_members	Hide members	Hide the group's member entities in the entity registry.	boolean	false	No
remember_on_state	Remember on/off state	When the group is turned off and on again, only the lights that were previously on will turn on.	boolean	false	No
restore_individual_brightness	Restore individual brightness	Each light recovers the brightness it had before the group was turned off.	boolean	false	No
remember_brightness	Maintain relative brightness	Keep brightness ratios between lights even at min/max group brightness.	boolean	false	No
debounce_enabled	Enable optimistic state debounce	Ignore member updates for a short period after a group command.	boolean	true	No
debounce_time	Debounce time	Milliseconds to ignore member updates after a group command.	integer (0–10000, step 100, ms)	2000	No

The defaults shown are the integration defaults. When called without a key, the existing value of that option is preserved, not reset to the default.

service: relative_light_group.set_options
target:
  entity_id: light.salon_rel
data:
  remember_on_state: true
  restore_individual_brightness: true
  debounce_time: 1500

relative_light_group.add_lights

Friendly name: Add lights to group

Append one or more lights to the group's member list. Lights already in the group are ignored. Lights that belong to another Relative Light Group are rejected.

Target: one or more light entities of this integration.

Field	Friendly name	Description	Type / domain	Default	Required
entities	Lights to add	One or more light entities to add to the group.	List of entity_id (domain light)	—	Yes

service: relative_light_group.add_lights
target:
  entity_id: light.salon_rel
data:
  entities:
    - light.lampara_lectura
    - light.aplique_pared

relative_light_group.remove_lights

Friendly name: Remove lights from group

Remove one or more lights from the group's member list. Lights not in the group are ignored. The call is rejected if the resulting list would be empty.

Target: one or more light entities of this integration.

Field	Friendly name	Description	Type / domain	Default	Required
entities	Lights to remove	One or more light entities to remove from the group.	List of entity_id (domain light)	—	Yes

service: relative_light_group.remove_lights
target:
  entity_id: light.salon_rel
data:
  entities:
    - light.aplique_pared

relative_light_group.set_lights

Friendly name: Replace group lights

Replace the group's member list with the provided lights. The list cannot be empty and cannot contain entities that belong to another Relative Light Group.

Target: one or more light entities of this integration.

Field	Friendly name	Description	Type / domain	Default	Required
entities	Lights	New ordered list of light entities for the group.	List of entity_id (domain light)	—	Yes

service: relative_light_group.set_lights
target:
  entity_id: light.salon_rel
data:
  entities:
    - light.lampara_lectura
    - light.aplique_pared
    - light.lampara_techo

Author

Felipe Urzúa
Email: cheerpipe@gmail.com
Repository: https://github.com/Cheerpipe/relative-light-group

License

MIT