From f009c1a1148a42a74d28dc4beaa73e8083d035f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20Pantalea=CC=83o?=
 <5808343+bgoncal@users.noreply.github.com>
Date: Mon, 20 Jul 2026 14:42:10 +0200
Subject: [PATCH] Document custom notification icons on iOS

Explain how notification_icon, icon_url, notification_icon_color and
color customize the notification icon on iOS, and note the iOS behavior
in the existing Android sections.
---
 docs/notifications/basic.md | 38 +++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/notifications/basic.md b/docs/notifications/basic.md
index d76dadf4d20..86d804205d6 100644
--- a/docs/notifications/basic.md
+++ b/docs/notifications/basic.md
@@ -212,6 +212,8 @@ automation:
 
 In Android you can set the `color` of the notification, you can use either the color name or the hex code.
 
+![iOS](/assets/iOS.svg)On iOS, `color` instead sets the background color of a notification icon. See [Notification Icon and Color](#notification-icon-and-color).
+
 ```yaml
 automation:
   - alias: "Notify of Motion color"
@@ -447,6 +449,8 @@ Not all devices support HTML formatting in notifications, and some formatting ma
 
 You can set the icon for a notification by providing the `icon_url`. The URL provided must be either publicly accessible or can be a relative path (i.e. `/local/icon/icon.png`), more details can be found in [attachments](attachments.md). It is important to note that if you set the `image` then Android will not show the icon for the notification, the `image` will be shown in its place. So the `message` will be shown with the `image` and with the image as the icon.
 
+![iOS](/assets/iOS.svg)On iOS, `icon_url` is used as the sender icon of a communication notification. See [Notification Icon and Color](#notification-icon-and-color).
+
 ```yaml
 automation:
   - alias: "Notify of Motion icon"
@@ -648,6 +652,8 @@ On Android you have the option for making a notification only alert once on the
 
 On Android you also have the option of changing the notification status bar icon to any icon on [Material Design](https://materialdesignicons.com/). By default the Home Assistant icon will appear. The expected format is the same in Home Assistant `mdi:cellphone`. If you provide an invalid icon name then no icon will be shown.
 
+![iOS](/assets/iOS.svg)On iOS, `notification_icon` instead sets the icon of a communication notification. See [Notification Icon and Color](#notification-icon-and-color).
+
 ```yaml
   - alias: Check your phone
     trigger:
@@ -686,6 +692,38 @@ On iOS 17.2+, `live_update: true` starts a **Live Activity** on the Lock Screen
 
 See [Live Activity and Live Updates](live-activities.md) for the full payload reference, examples, and platform-specific behavior.
 
+### Notification Icon and Color
+
+On iOS, you can give a notification a custom sender icon. When you do, the notification is shown as a communication notification, the same rounded-avatar style used by messaging apps. This requires the notification to have a `title`, which is used as the sender name.
+
+Provide the icon in one of two ways:
+
+- `icon_url`: a URL to an image to use as the icon. It must be publicly accessible or a relative path (such as `/local/icon/icon.png`), following the same rules as [attachments](attachments.md).
+- `notification_icon`: a [Material Design Icon](https://pictogrammers.com/library/mdi/) slug, such as `mdi:cellphone`.
+
+If both are set, `icon_url` takes precedence.
+
+When you use a `notification_icon`, you can also set its colors. These have no effect on an `icon_url` image. Both accept a hex value, such as `#03A9F4`.
+
+- `notification_icon_color`: the color of the icon glyph. Defaults to white.
+- `color`: the background color behind the icon. Defaults to the Home Assistant theme color.
+
+```yaml
+automation:
+  - alias: "Notify with a custom icon"
+    trigger:
+      ...
+    action:
+      - action: notify.mobile_app_<your_device_id_here>
+        data:
+          title: "Washing machine"
+          message: "The cycle has finished"
+          data:
+            notification_icon: "mdi:washing-machine"
+            notification_icon_color: "#FFFFFF"
+            color: "#03A9F4"
+```
+
 ### Sounds
 By default the default notification sound (Tri-tone on iOS) will be played upon receiving a notification. See the [Sounds documentation](sounds.md) for details of the available sounds and how to add custom sounds. The default notification sounds (Tri-tone) can be disabled by setting `sound` to `none` in the data payload: