Add priority field to the To-do entity model

[njoerd114]

Background

The TodoItem dataclass currently has six fields: summary, uid, status, due, description, and completed. Priority is missing — despite being one of the most common fields in task management. Four of the six major todo apps (Todoist, Apple Reminders, TickTick, Microsoft To Do) implement priority levels, and RFC 5545 defines a PRIORITY property for VTODO components.

There is prior work in home-assistant/core#159912 that added priority with CalDAV support. That PR was closed as stale after @MartinHjelmare noted that changes to an entity model require an architecture discussion first. This discussion fulfills that requirement.

Proposal

Add a priority field to the TodoItem dataclass and a SET_PRIORITY_ON_ITEM feature flag to TodoListEntityFeature. This follows the existing TodoItemFieldDescription extension pattern already used for due_date, due_datetime, and description — no new machinery required.

Data structure

PR #159912 stored priority as a raw integer (1-9 per RFC 5545). During review, @tr4nt0r raised that "most clients implement user-friendly schemes like low/medium/high, internally mapped to 1-9." I agree. The proposed approach is a StrEnum with three levels:

class TodoItemPriority(StrEnum):
    """Priority of a To-do item."""

    HIGH = "high"
    MEDIUM = "medium"
    LOW = "low"

Priority is None when unset (matching RFC 5545 value 0 = undefined).

Rationale for a StrEnum over raw integers:

• Consistent with HA conventions. TodoItemStatus is already a StrEnum. Priority should follow the same pattern.
• Clean UI and service interface. Users pass "high" / "medium" / "low" in service calls. No need to know that Todoist uses 1-4 or iCal uses 1-9.
• Sufficient granularity. Every known integration's priority system maps cleanly to three levels (see below). A fourth "critical"/"urgent" tier isn't warranted — only Todoist has four levels and their P1/P2 are both functionally "high."
• Integration flexibility preserved. Integrations that use iCal/CalDAV can still store the original 1-9 values in their backend and map to/from the enum at the boundary.

Integration impact

Mapping table for integrations that support priority in their backends:

Integration	Backend priorities	Mapping to TodoItemPriority
local_todo (iCal)	RFC 5545 PRIORITY 1-9	HIGH=1, MEDIUM=5, LOW=9
caldav	RFC 5545 PRIORITY 1-9	Same as local_todo
todoist	P1 (highest) – P4 (lowest)	HIGH=P1/P2, MEDIUM=P3, LOW=P4
habitica	trivial, easy, medium, hard	HIGH=hard, MEDIUM=medium/easy, LOW=trivial
google_tasks	No priority support	Would not set the feature flag

Of the 13 integrations currently implementing TodoListEntity, 5-6 have a meaningful concept of priority. Shopping and recipe list integrations (Bring, Mealie, OurGroceries, etc.) would simply not set SET_PRIORITY_ON_ITEM in their supported features — no changes needed on their side.

Implementation scope

The change is small and follows a well-established pattern:

• const.py: Add TodoItemPriority StrEnum, SET_PRIORITY_ON_ITEM = 128 feature flag, ATTR_PRIORITY constant
• __init__.py: Add priority: TodoItemPriority | None = None to TodoItem, add one TodoItemFieldDescription entry to TODO_ITEM_FIELDS
• services.yaml: Add priority field to add_item and update_item with a select selector and feature filter
• strings.json: Add translatable strings for the priority field and its options

Estimated ~50-80 lines changed. No breaking changes — the new field is optional and gated behind a feature flag. A companion frontend PR will be needed for the todo card to display and edit priority.

This same pattern (new TodoItem field + feature flag + TodoItemFieldDescription entry) could be reused for future additions like labels or assignee, but those are out of scope for this discussion.

Prior art

• Add priority to ToDo as defined in RFC 5545 core#159912 — Prior implementation (closed stale, +44/-9 lines). The approach was sound; the main gap was this architecture discussion.
• RFC 5545, Section 3.8.1.9 — Defines PRIORITY as an integer 0-9 for VTODO components.
• Community requests — Multiple forum threads requesting todo enhancements (recurring tasks, labels, priority), indicating active user interest in a more capable todo platform.
• Industry consensus — Todoist (P1-P4), Apple Reminders (low/medium/high), TickTick (5 levels), Microsoft To Do (important flag). Priority is a standard feature in task management.

---

[surfingbytes]

You beat me to it :) I'm the developer of the linked PR and was just about to start this discussion. What I prepared:

There are some integrations providing to-do lists. Each of their providers (Todoist, MS Todo, Nextcloud, Habitica...) support different priority range (1-4, 1-9...), and some may even work the completely oposite way (1 in some integration can mean top prioriy while 1 in other integrarion can mean lowest priority). Because of that, HA should implement priority in a way that allows any integration to map to it - RFC 5545.
Supporting this, we support all cases. When we internally save 1-9 (+ 0 -> no priority set), then the integrations can easily do:

• Habitica (trivial, easy, medium, hard)
  • save: hard -> 1, medium -> 3, easy -> 5, trivial - > 7
  • load: 1-2 -> hard, 3-4 -> medium, 5-6 -> easy, 7-9 -> trivial
• Todoist (1-4)
  • save: map 1-4 to 1-9, for example: 1->1, 2->3, 3->5, 4->7
  • load: map 1-9 to1-4, for example: 1-2 -> 1, 3-4 -> 2, 5-6 -> 3, 7-9 ->4

This provides standardized way of internal priority storage, while allowing integrations to use whatever scale they want. The RFC 5545 (values 1-9) acts as interface between all integrations. So it will then also be possible to have todo item saved by todoist, and shown by "habitica manner", because the underlying data have the same format/range for all integrations.

[tr4nt0r]

This coincides with the recommendations from the RFC 5545:

https://datatracker.ietf.org/doc/html/rfc5545#page-90

Description:  This priority is specified as an integer in the range 0
      to 9.  A value of 0 specifies an undefined priority.  A value of 1
      is the highest priority.  A value of 2 is the second highest
      priority.  Subsequent numbers specify a decreasing ordinal
      priority.  A value of 9 is the lowest priority.

      A CUA with a three-level priority scheme of "HIGH", "MEDIUM", and
      "LOW" is mapped into this property such that a property value in
      the range of 1 to 4 specifies "HIGH" priority.  A value of 5 is
      the normal or "MEDIUM" priority.  A value in the range of 6 to 9
      is "LOW" priority.

      A CUA with a priority schema of "A1", "A2", "A3", "B1", "B2", ...,
      "C3" is mapped into this property such that a property value of 1
      specifies "A1", a property value of 2 specifies "A2", a property
      value of 3 specifies "A3", and so forth up to a property value of
      9 specifies "C3".```

[allenporter]

I am supportive of this proposal.

Rationale:

• it is consistent with our pattern of supported RFC5545 attributes
• clear use case across multiple integrations.
• Proposal to map to a 3 level priority (as spelled out in the RFC example) seems right given the context used within Home Assistant where we tend to make compromises (e.g. similar to not supporting cancelled events).

[allenporter]

Caveat: This will likely need to be an orthogonal concept from ordering in the list, given that has an explicit API already for ordering. However, i suspect this may come up from a user perspective (e.g. put my high priority items at the top of the list). Integrations may do that naturally (e.g. if they don't support reordering etc), but it can't be fully baked into the API.

[MartinHjelmare]

I've added this to the architecture meeting agenda.

[MartinHjelmare]

We've discussed this proposal today in the architecture meeting.

The conclusion is that we want a clearer motivation for restricting the core API to 3 levels instead of the 9 levels in the RFC. We notice that doing so, will cause all mentioned supporting integrations to lose resolution. A question that was put was: Would it be possible to collapse the 1-9 levels only in the frontend with appropriate naming, and keep all RFC 1-9 levels in the backend?

[allenporter]

Would it be possible to collapse the 1-9 levels only in the frontend with appropriate naming, and keep all RFC 1-9 levels in the backend?

Seems fine from my pov to treat this as display only thing.

[MartinHjelmare]

@njoerd114 are you ok with this? Will you update the proposal at the top?