Sortable List Card

Configuration

Every option, what it does, and how to use it. Required fields are marked with *.

In a hurry?
The Examples page has minimal configs you can paste straight into your dashboard, including the HEMS priority list.
Card options
Type, entity, value format
Display
Handle, arrows, rank, state
Save action
Persist via any service
Item options
Key, entity, name, icon

Card options

Top-level configuration — type, the items list, the read-back entity, and how the order value is stored.

example.yaml
type: custom:sortable-list-card
title: My order
entity: input_text.my_order
value_format: csv
items:
  - key: alpha
    name: Alpha
  - key: beta
    name: Beta
type*stringrequired
custom:sortable-list-card
items*arrayrequired
The list rows. Each item is documented in the Item options section. Every item needs a key or an entity.
entitystring
Entity whose state holds the current order (the read-back source of truth). Optional — omit it for write-only persistence through a custom service.
value_formatstringdefault csv
How the order is parsed from / formatted into the entity value. One of csv (e.g. a,b,c) or json (e.g. ["a","b","c"]).
titlestring
Optional card title shown above the list.

Display

Toggle the row affordances: the drag handle, arrow buttons, rank number, and entity state.

example.yaml
show_handle: true
show_arrows: true
show_rank: true
show_state: false
show_handlebooleandefault true
Show the drag handle on the left of each row.
show_arrowsbooleandefault true
Show the up/down arrow buttons. They are disabled at the list boundaries.
show_rankbooleandefault true
Show the 1-based position number on each row.
show_statebooleandefault false
Show the entity's state as secondary text (entity-backed items only).

Save action

The service called on every reorder. This is what makes the card generic.

When save_action is omitted but entity is set, the card defaults to input_text.set_value on that entity. Provide your own to call any service instead — a script, a number.set_value, an MQTT publish, etc.

Inside data and target, these placeholders are replaced with the new order on every reorder:

example.yaml
# Default behaviour (no save_action needed):
entity: input_text.my_order

# Or a fully custom service:
save_action:
  service: script.save_order
  data:
    order: "{value_list}"   # an actual list
    csv: "{value_csv}"      # "a,b,c"
service*stringrequired
The service to call, in domain.service form (e.g. input_text.set_value or script.save_order).
dataobject
Service data. Use the placeholders below for the new order. When omitted and the service is the default, { entity_id, value: "{value}" } is sent.
targetobject
Optional service target (entity_id, device_id, area_id). Placeholders are substituted here too.
{value}string
The order formatted per value_format (a CSV or JSON string).
{value_csv}string
Comma-separated keys, e.g. a,b,c.
{value_json}string
JSON array string, e.g. ["a","b","c"].
{value_list}array
The raw array. Use it when the string is exactly {value_list} — the value is replaced with an actual list rather than a string.

Item options

Each entry in the items array. Items can be plain (key + label) or backed by an entity.

Reference an entity to pull its friendly name, icon, and (with show_state) its state automatically. Set name or icon to override. The stored key defaults to the entity id when omitted.

example.yaml
items:
  - key: battery
    name: Battery
    icon: mdi:battery-charging
  - entity: light.kitchen       # key, name & icon inferred
  - entity: light.living_room
    name: Living room            # override the label
keystring
Stable identifier stored in the order. Defaults to the item's entity when omitted — at least one of key / entity is required.
entitystring
Entity to pull the friendly name, icon, and state from.
namestring
Label override. Falls back to the entity's friendly name, then the key.
iconstring
MDI icon override. Falls back to the entity's icon.