Add an LVGL widget to a page
esphome_lvgl_add_widgetAdd an LVGL widget to an ESPHome page and save the full YAML config. Creates a .bak backup; use for widget insertion without manual editing.
Instructions
Add an LVGL widget to a page on an ESPHome device and save the whole config.
Appends {widget_type: properties} to the page's widgets list, then
rewrites the entire device YAML file via yaml.dump — comments, blank
lines and YAML anchors/aliases elsewhere in the file are NOT preserved.
A <file>.bak copy of the previous content is written first so the
original formatting can be recovered manually. Lambda callbacks
(on_click, on_value_changed) are not supported here — add them
manually via esphome_get_config/esphome_write_config. Calling this
twice with the same arguments adds two separate widgets.
Use when: adding one widget to an existing LVGL page without
hand-editing the full YAML.
Not for: removing a widget — use esphome_lvgl_delete_widget; not for
lambda callbacks or other structural edits — use
esphome_get_config/esphome_write_config. After adding, run
esphome_lvgl_validate/esphome_validate_config, then
esphome_compile_device and esphome_upload_device to deploy.
Returns: {"success": True, "name": ..., "bytes": ..., "backup": ..., "added": <widget_type>, "to_page": <page_id>} on success.
Errors: {"error": "..."} when the file can't be found/parsed, when
there is no lvgl: section, when page_id doesn't exist, or when the
save itself fails ({"success": False, "error": ...}).
Limits: rewrites and overwrites the whole file; only the pre-write
content is recoverable, via the .bak copy.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | LVGL page ID to add the widget to, from `esphome_lvgl_get_pages`. | |
| properties | Yes | Widget properties, e.g. {'id': ..., 'x': ..., 'y': ..., 'width': ..., 'height': ..., 'text': ..., 'value': ..., 'styles': ...}. | |
| device_name | Yes | Device name, with or without the '.yaml' suffix, e.g. 'kitchen_display'. | |
| widget_type | Yes | LVGL widget type, e.g. 'label', 'button', 'slider', 'arc', 'switch', 'spinbox', 'img', 'line', 'meter'. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||