Home ▸ Integrations

To-do list

The To-do list integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides to-do list entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more], allowing other integrations to integrate to-do lists into Home Assistant. To-do lists are shown on the To-do lists dashboard for tracking items and whether or not they have been completed.

Note

Building block integration

This to-do list is a building block integration that cannot be added to your Home Assistant directly but is used and provided by other integrations.

A building block integration differs from the typical integration that connects to a device or service. Instead, other integrations that do integrate a device or service into Home Assistant use this to-do list building block to provide entities, services, and other functionality that you can use in your automations or dashboards.

If one of your integrations features this building block, this page documents the functionality the to-do list building block offers.

For example, Local to-do is a fully local integration to create to-do lists and tasks within your Home Assistant instance, Shopping list specifically for shopping that can be added to with Assist, or other integrations work with online services providing to-do list data.

Viewing and managing to-do lists

Each to-do list is represented as its own entity in Home Assistant and can be viewed and managed on a to-do list dashboard. You can find the to-do list dashboard in the main sidebar of your Home Assistant instance.

The state of a to-do list entity

The state of a to-do list entity is a number, which represents the number of incomplete items in the list.

Screenshot showing the state of a to-do list entity in the developer tools.

In addition, the entity can have the following states:

Unavailable: The entity is currently unavailable.
Unknown: The state is not yet known.

Blueprint to add an item to a dedicated list

This blueprint allows you to create a script to add an item to a pre-configured to-do list.

List of triggers

The To-do list integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following triggers. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.

To-do item added (todo.item_added) Triggers when a to-do item is added to a list.
To-do item completed (todo.item_completed) Triggers when a to-do item is marked as done.
To-do item removed (todo.item_removed) Triggers when a to-do item is removed from a list.

For an overview of every trigger across all integrations, see the triggers reference.

List of conditions

The To-do list integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following conditions. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.

All to-do items completed (todo.all_completed) Tests if all to-do items are completed in one or more to-do lists.
Incomplete to-do items (todo.incomplete) Tests the number of incomplete to-do items in one or more to-do lists.

For an overview of every condition across all integrations, see the conditions reference.

Actions

Some to-do list integrations allow Home Assistant to manage the to-do items in the list. The actions provided by some to-do list entities are described below or you can read more about actions.

Action: Get items

The todo.get_items action gets to-do items from a to-do list. A to-do list target is selected with a target selector. The data payload supports the following fields:

Data attribute	Optional	Description	Example
`status`	yes	Only return to-do items with this status.	`needs_action`, `completed`

This is a full example that returns all to-do items that have not been completed:

action: todo.get_items
target:
  entity_id: todo.vacation_preparation
data:
  status:
    - needs_action

This is an example response to the get items action:

todo.vacation_preparation:
  items:
    - summary: Water plants
      uid: 01244b28-e604-11ee-a0a4-e45f0197c057
      status: needs_action
    - summary: turn down heating
      uid: ae993df4-e604-11ee-a0a4-e45f0197c057
      status: needs_action

Action: Add item

The todo.add_item action adds a new to-do item. A to-do list target is selected with a Target Selector and the data payload supports the following fields:

Data attribute	Optional	Description	Example
`item`	no	The name/summary of the to-do item.	Submit income tax return
`due_date`	yes	The date the to-do item is expected to be completed.	2024-04-10
`due_datetime`	yes	The date and time the to-do item is expected to be completed.	2024-04-10 23:00:00
`description`	yes	A more complete description than the one provided by the summary.	Collect all necessary documents and submit the final return.

Only one of due_date or due_datetime may be specified.

This is a full example in YAML:

action: todo.add_item
target:
  entity_id: todo.personal_tasks
data:
  item: "Submit Income Tax Return"
  due_date: "2024-04-10"
  description: "Collect all necessary documents and submit the final return."

Action: Update item

The todo.update_item action updates a to-do item. A to-do list target is selected with a Target Selector and the data payload supports the following fields:

Data attribute	Optional	Description	Example
`item`	no	The name/summary of the to-do item. In some cases, for example if you have items with the same name, it can make sense to use the UID instead of the name. To find the UID of an item, perform a `get_items` action on the to-do list.	`Submit income tax return` or `01244b28-e604-11ee-a0a4-e45f0197c057`
`rename`	yes	The new name of the to-do item.	Something else
`status`	yes	The overall status of the to-do item.	`needs_action` or `completed`
`due_date`	yes	The date the to-do item is expected to be completed.	2024-04-10
`due_datetime`	yes	The date and time the to-do item is expected to be completed.	2024-04-10 23:00:00
`description`	yes	A more complete description than the one provided by the summary.	Collect all necessary documents and submit the final return.

At least one of rename or status is required. Only one of due_date or due_datetime may be specified. This is a full example that updates the status and the name of a to-do item.

action: todo.update_item
target:
  entity_id: todo.personal_tasks
data:
  item: "Submit income tax return"
  rename: "Something else"
  status: "completed"

Action: Remove item

The todo.remove_item action removes a to-do item. A to-do list target is selected with a Target Selector, and the data payload supports the following fields:

Data attribute	Optional	Description	Example
`item`	no	The name/summary of the to-do item. In some cases, for example if you have items with the same name, it can make sense to use the UID instead of the name. To find the UID of an item, perform a `get_items` action on the to-do list.	`Submit income tax return` or `01244b28-e604-11ee-a0a4-e45f0197c057`

This is a full example that deletes a to-do Item with the specified name.

action: todo.remove_item
target:
  entity_id: todo.personal_tasks
data:
  item: "Submit income tax return"

Action: Remove completed items

The todo.remove_completed_items action removes all completed to-do items. A to-do list target is selected with a Target Selector.

This is a full example that deletes all completed to-do items.

action: todo.remove_completed_items
target:
  entity_id: todo.personal_tasks

To-do list automation examples

To-do list triggers and conditions make it easier to react to changes in a list or check whether a list still needs attention.

Tip

You don’t need to edit YAML to use these examples. Copy a YAML snippet from this page, open the automation editor in Home Assistant, and press Ctrl+V (or Cmd+V on Mac). Home Assistant automatically converts the pasted YAML into the visual editor format, whether it’s a full automation, a single trigger, a condition, or an action.

Automation: send a notification when someone adds a shopping item

If you share a shopping list with your household, this automation lets you know right away when someone adds a new item.

Trigger: To-do item added
Target: Shopping list
Action: Send a notification message
- Target: My Device (notify.my_device)

YAML example for a shopping list notification

Automation

alias: "Notify me when a shopping item is added"
triggers:
  - trigger: todo.item_added
    target:
      entity_id: todo.shopping_list
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: >
        A new item was added to the shopping list.

Automation: lock the front door when the evening checklist is finished

If you keep an evening checklist in Home Assistant, this automation locks the front door after the last task is marked complete.

Trigger: To-do item completed
Condition: All to-do items completed
Target: Evening checklist
Action: Lock lock

YAML example for locking up after the evening checklist is done