home-assistant.io/source/_integrations/todo.markdown

title, description, ha_domain, ha_release, ha_category, ha_quality_scale, ha_codeowners, ha_integration_type

title	description	ha_domain	ha_release	ha_category	ha_quality_scale	ha_codeowners	ha_integration_type
To-do list	Instructions on how to use to-do lists within Home Assistant.	todo	2023.11	To-do list	internal	@home-assistant/core	entity

The to-do list integration provides to-do list entities, allowing other integrations to integrate to-do lists into Home Assistant. To-do lists are shown on the to-do list dashboard for tracking items and whether or not they have been completed.

{% include integrations/building_block_integration.md %}

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.

Services

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

Service todo.get_items

Get 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:

Service 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:

service: todo.get_items
target:
  entity_id: todo.personal_tasks
data:
  status:
    - needs_action

Service todo.add_item

Add a new to-do item. A to-do list target is selected with a Target Selector and the data payload supports the following fields:

Service data attribute	Optional	Description	Example
item	no	the name 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 of service call in YAML:

service: 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."

### Service `todo.update_item`

Update a to-do item. A to-do list `target` is selected with a [Target Selector](/docs/blueprint/selectors/#target-selector) and the `data` payload supports the following fields:

| Service data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | --------|
| `item` | no | The name of the to-do Item to update. | Submit income tax return
| `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 of a service call that updates the status and the name of a to-do item.

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

Service todo.remove_item

Removing a to-do item. A to-do list target is selected with a Target Selector, and the data payload supports the following fields:

Service data attribute	Optional	Description	Example
item	no	The name of the to-do item.	Submit income tax return

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

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

Service todo.remove_completed_items

Removes all completed to-do items. A to-do list target is selected with a Target Selector.

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

service: todo.remove_completed_items
target:
  entity_id: todo.personal_tasks