From 2aee1e8ea45c5093052a823e09fd8fbc6f5f1c5e Mon Sep 17 00:00:00 2001
From: DeoJin <DeoJin@users.noreply.github.com>
Date: Tue, 17 Mar 2026 04:10:03 +0100
Subject: [PATCH] docs: document how to set attachment alt text

---
 README.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/README.md b/README.md
index 323f98e7d..0e836f193 100644
--- a/README.md
+++ b/README.md
@@ -357,6 +357,18 @@ addEventListener("trix-attachment-add", (event) => {
 })
 ```
 
+You can also set image-specific attributes in the same handler. For example, set an attachment's `alt` text with `setAttributes`:
+
+```js
+addEventListener("trix-attachment-add", (event) => {
+  if (event.attachment.file instanceof File) {
+    event.attachment.setAttributes({ alt: "A friendly description of the image" })
+  }
+})
+```
+
+`figcaption` content is edited through the attachment `caption`, but it does not automatically become the image's `alt` text. If you need both, set them explicitly.
+
 # Editing Text Programmatically
 
 You can manipulate a Trix editor programmatically through the `Trix.Editor` interface, available on each `<trix-editor>` element through its `editor` property.