Entity Settings

Configure entity display, actions, and behavior options

Each entity in the plasmoid can be customized with display options, service actions, and notification settings. This page documents all available configuration options found in the entity configuration dialog.

Opening Entity Settings

Access entity settings by:

• Clicking Edit on an existing entity in the entity list
• Clicking Add to configure a new entity

The entity configuration dialog (ConfigItem.qml) provides a form with all customization options.

Basic Entity Configuration

Entity ID

The Entity field (ConfigItem.qml:13-23) specifies which Home Assistant entity to display.

• Required field - must be set to a valid entity ID
• Supports autocomplete with all available entities
• Format: domain.entity_name (e.g., light.living_room, sensor.temperature)

The dialog’s OK button is only enabled when a valid entity ID is entered (ConfigItems.qml:172).

Custom Name

The Name field (ConfigItem.qml:43-48) allows you to override the default friendly name.

• Optional - leave blank to use the entity’s friendly_name attribute
• Custom names appear in the plasmoid widget and configuration list
• Placeholder shows the entity’s current friendly name from Home Assistant

Example:

• Entity: sensor.outdoor_temperature
• Default friendly name: “Outdoor Temperature Sensor”
• Custom name: “Outside Temp”

Custom Icon

The Icon field (ConfigItem.qml:50-62) lets you specify a custom icon for the entity.

• Optional - leave blank to use the entity’s default icon
• Supports two icon formats:
  • MDI icons: mdi:icon-name (e.g., mdi:lightbulb, mdi:thermometer)
  • Plasma icons: plasma:icon-name (e.g., plasma:home, plasma:weather)
• Icon preview appears next to the input field
• Placeholder shows the entity’s current icon from Home Assistant

Browse available icons at:

• MDI icons: materialdesignicons.com
• Plasma icons: Available through KDE icon themes

Display Options

Display Attribute

The Display attribute option (ConfigItem.qml:25-41) allows you to show a specific entity attribute instead of the state.

1. Step 1: Enable Attribute Display
2. Check the checkbox next to Display attribute.
3. Step 2: Select Attribute
4. Choose an attribute from the dropdown menu:

Example use cases:

• Show temperature attribute of a climate entity
• Display brightness of a light entity
• Show battery level of a sensor

The attribute dropdown is populated from the entity’s current attributes (ConfigItem.qml:34). Different entity types have different available attributes.

Service Actions

Service actions define what happens when you interact with the entity in the plasmoid widget. Actions are configured by selecting services from your Home Assistant instance.

Click Action

The Click action (ConfigItem.qml:98-102) defines what service is called when you click the entity.

1. Check the checkbox to enable click actions
2. Select a service from the dropdown
3. Available services are filtered by the entity’s domain

Example configurations:

• light.toggle - Toggle light on/off
• switch.turn_on - Turn on a switch
• climate.set_temperature - Open temperature control

The service automatically targets the configured entity. You don’t need to specify the target separately (model.mjs:59-63).

Scroll Action

The Scroll action (ConfigItem.qml:104-119) defines what happens when you scroll on the entity with your mouse wheel.

1. Check the checkbox to enable scroll actions
2. Select a service from the dropdown
3. Select a data field for the scroll operation

How it works:

• Only services with numeric fields are available (ConfigItem.qml:107)
• The numeric field must match an entity attribute (ConfigItem.qml:125)
• Scrolling up/down adjusts the numeric value

Example configurations:

• light.turn_on with brightness field - Adjust light brightness
• climate.set_temperature with temperature field - Adjust thermostat
• fan.set_percentage with percentage field - Control fan speed

The scroll action dropdown is dynamically filtered to show only services with numeric fields that match the entity’s attributes (ConfigItem.qml:121-128).

Service Target and Data

When you configure an action, the plasmoid automatically constructs the service call (model.mjs:59-65):

{
  service: "light.turn_on",
  domain: "light",
  target: { entity_id: "light.living_room" },
  data_field: "brightness"  // For scroll actions
}

• service: The full service name (e.g., light.toggle)
• domain: Automatically extracted from entity ID
• target: Always set to the configured entity
• data_field: The attribute to modify (scroll actions only)

Notifications

The Notify about changes checkbox (ConfigItem.qml:64-68) enables desktop notifications when the entity’s state or attributes change.

• Enabled: Desktop notifications appear when the entity changes
• Disabled: No notifications are shown

Notifications display:

• Entity name
• New state or attribute value
• Entity icon

Enable notifications for important entities like door sensors, alarms, or critical status indicators.

Configuration Model

The ConfigEntity model (model.mjs:24-52) stores all entity settings:

• entity_id: Home Assistant entity identifier (required)
• name: Custom display name (optional)
• icon: Custom icon path (optional)
• attribute: Attribute to display instead of state (optional)
• default_action: Click action configuration (optional)
• scroll_action: Scroll action configuration (optional)
• notify: Enable change notifications (boolean)
• domain: Automatically derived from entity_id

Reactive Properties

The configuration model includes reactive properties (model.mjs:26-39):

• Changing entity_id automatically updates the domain
• Actions are validated when entity_id changes
• Invalid actions (wrong domain) are automatically cleared (model.mjs:69-72)

This ensures action configurations remain valid when switching entities.

Validation

The entity configuration dialog validates settings:

• Required: Entity ID must be set and valid
• Optional: All other fields can be left empty
• Service availability: Action dropdowns only show applicable services
• Attribute availability: Attribute dropdown only shows actual entity attributes

The OK button remains disabled until a valid entity ID is entered (ConfigItems.qml:172-177).

Advanced Configuration

Service Field Detection

The plasmoid intelligently detects numeric service fields (ConfigItem.qml:121-128):

1. Retrieves service definition from Home Assistant
2. Recursively searches for fields with selector.number
3. Filters to only fields matching entity attributes
4. Populates the data field dropdown

This ensures scroll actions only appear for services that support numeric adjustments on the current entity.

Domain-Based Actions

Actions are filtered by entity domain to ensure compatibility:

• A light entity only shows light.* services by default
• Changing entity_id revalidates all configured actions
• Mismatched domain actions are automatically cleared

Examples

Example 1: Living Room Light

Entity: light.living_room
Name: Living Room
Icon: mdi:ceiling-light
Click action: light.toggle
Scroll action: light.turn_on (brightness)
Notify: Disabled

Example 2: Temperature Sensor

Entity: sensor.bedroom_temperature
Name: Bedroom Temp
Icon: mdi:thermometer
Display attribute: temperature
Click action: None
Scroll action: None
Notify: Enabled

Example 3: Thermostat Control

Entity: climate.living_room
Name: Thermostat
Icon: mdi:thermostat
Click action: climate.toggle
Scroll action: climate.set_temperature (temperature)
Notify: Disabled

Next Steps

Adding Entities

Learn how to add entities to your plasmoid

Backup & Restore

Save and restore entity configurations