From 6f800ad3f9e606b5639c9eea3ea2d3a3b5dfebd4 Mon Sep 17 00:00:00 2001
From: clydebarrow <2366188+clydebarrow@users.noreply.github.com>
Date: Thu, 28 Aug 2025 21:30:47 +1000
Subject: [PATCH 1/2] [mapping] Update docs

---
 content/components/mapping.md | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/content/components/mapping.md b/content/components/mapping.md
index 57ab2dcc9b..b85f845517 100644
--- a/content/components/mapping.md
+++ b/content/components/mapping.md
@@ -3,7 +3,8 @@ description: "Mapping Component"
 title: "Mapping Component"
 ---
 
-The `mapping` component allows you to create a map or dictionary that allows a one-to-one translation from keys to values. This enables e.g. mapping a string to a number or vice versa, or mapping a string such as a weather condition to an image.
+The `mapping` component allows you to create a map or dictionary that allows a one-to-one translation from keys to
+values. This enables e.g. mapping a string to a number or vice versa, or mapping a string such as a weather condition to an image.
 
 ```yaml
 # Example configuration entry
@@ -43,9 +44,14 @@ You can also map to a class. This is useful when you want to map to a more compl
 - `color`  : Maps to a predefined [Color](#config-color). The values should each be a color ID.
 - The name of a C++ class defined by ESPHome, e.g. `Component`. The values should each be a ID of that class.
 
+
 ## Using a mapping
 
-A mapping defined in this component can be used in lambdas in other components. The mapping can be accessed using the `id` function, and the value can be looked up using the `[]` operator as per the above example.
+A mapping defined in this component can be used in lambdas in other components. The mapping can be accessed using
+the ``id`` function, and the value can be looked up using the ``[]`` operator as per the above example, or the ``get`` function.
+A map may be updated at run time using a lambda call, e.g. ``map.set("key", value)``.
+
+Maps are stored in RAM, but will use PSRAM if available.
 
 A more complex example follows:
 
@@ -84,8 +90,14 @@ display:
   - platform: ...
     # update the display drawing random text in random colors
     lambda: |-
-      auto color = color_map[random_uint32() % 3];
+      auto color = color_map.get(random_uint32() % 3]); # Uses get() to index the color_map
       it.printf(100, 100, id(roboto20), color, id(string_map)[random_uint32() % 3].c_str(), Color(0));
+
+    on_...:
+      then:
+        - lambda: |-
+              id(color_map).set(2, Color::random_color());
+
 ```
 
 ## See Also

From 65f1b99afc103e1ec23f7d13ffa0508f46f1982e Mon Sep 17 00:00:00 2001
From: clydebarrow <2366188+clydebarrow@users.noreply.github.com>
Date: Thu, 28 Aug 2025 21:32:39 +1000
Subject: [PATCH 2/2] Whitespace

---
 content/components/mapping.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/content/components/mapping.md b/content/components/mapping.md
index b85f845517..6722d9f123 100644
--- a/content/components/mapping.md
+++ b/content/components/mapping.md
@@ -44,7 +44,6 @@ You can also map to a class. This is useful when you want to map to a more compl
 - `color`  : Maps to a predefined [Color](#config-color). The values should each be a color ID.
 - The name of a C++ class defined by ESPHome, e.g. `Component`. The values should each be a ID of that class.
 
-
 ## Using a mapping
 
 A mapping defined in this component can be used in lambdas in other components. The mapping can be accessed using