When you post an image on Mastodon without alternative text, screen readers and text-only clients cannot describe what is in the picture. The Mastodon interface shows a warning icon next to images that lack alt text, and some instances may block the post entirely. Adding alt text ensures your images are accessible to blind and low-vision users and helps your content reach a wider audience. This article explains exactly how to add alt text on the web, through official mobile apps, and through third-party clients, along with common pitfalls to avoid.
Key Takeaways: Adding Alt Text to Mastodon Images
- Image attachment button (paperclip icon): Opens the file picker to upload images; alt text fields appear after upload.
- Edit button (pencil icon) on uploaded image: Opens the alt text input field where you type the description.
- Alt text length limit: Mastodon accepts up to 1,500 characters per image description.
What Alt Text Does on Mastodon and Why It Matters
Alt text is a written description of an image that is embedded in the image metadata. When a screen reader encounters an image with alt text, it reads the description aloud to the user. Without alt text, the screen reader may say only “image” or read the filename, which is rarely helpful.
Mastodon was built with accessibility as a core value. The software explicitly warns you before posting if any attached image lacks alt text. Some Mastodon instances enforce a policy that blocks posts containing images without alt text. Even if your instance does not enforce this, adding alt text is considered good etiquette in the fediverse.
What Makes Good Alt Text
Good alt text describes the content and function of the image in a concise way. For a photograph of a cat sleeping on a sofa, write “A gray tabby cat curled up on a blue fabric sofa.” Do not write “image of cat” or “cat picture.” Include text that appears in the image if it is relevant to the post. For decorative images that add no information, you can mark them as decorative if your client supports that option, but Mastodon does not have a built-in decorative flag.
Steps to Add Alt Text on the Mastodon Web Interface
The web interface is the most common way to post on Mastodon. The steps below work on all standard Mastodon web clients, including the official interface and most custom front ends such as Elk or Pinafore.
- Open the compose box
Click the text area at the top of the home timeline or click the compose icon if you are using a narrow layout. The compose box expands to show formatting options. - Attach an image
Click the paperclip icon or the camera icon in the compose toolbar. Select one or more image files from your computer. Mastodon supports JPEG, PNG, GIF, and WebP formats. The maximum file size depends on your instance configuration, typically 8 MB or 16 MB. - Locate the alt text field
After the image uploads, a thumbnail appears in the compose box. Below the thumbnail, you see a small pencil icon labeled “Edit” or “Describe” depending on your theme. Click that icon. - Type the description
A text input field opens. Type your alt text here. You can enter up to 1,500 characters. Use plain language. Describe only what is visible in the image. Do not add editorial comments like “beautiful” or “cute.” - Save the description
Press Enter or click the checkmark icon to save the alt text. The pencil icon changes to indicate that the image now has a description. If you attached multiple images, repeat steps 3 through 5 for each image. - Post your toot
Write your text in the compose box. Click the “Publish” button. If you try to post without alt text on any image, Mastodon shows a warning dialog. Click “Add description” to go back and add alt text, or click “Publish anyway” to bypass the warning. We recommend always adding the description.
Steps to Add Alt Text on Mastodon Mobile Apps
The official Mastodon mobile apps for iOS and Android follow the same logic as the web interface. The labels and icons may appear slightly different, but the workflow is identical.
On iOS (Official Mastodon App)
- Tap the compose button
Tap the pencil icon or the plus icon in the bottom center of the screen. - Attach an image
Tap the photo icon in the compose toolbar. Select an image from your camera roll. - Tap the edit icon
After the image thumbnail appears, tap the small “Edit” label or the pencil icon below the thumbnail. - Enter the alt text
Type your description in the text field that appears. Tap “Done” on the keyboard to save. - Post
Tap “Publish” in the top right corner. The app warns you if any image lacks alt text.
On Android (Official Mastodon App)
- Tap the compose button
Tap the pencil icon at the bottom of the screen. - Attach an image
Tap the image icon in the toolbar. Select an image from your gallery. - Tap the description button
Below the image thumbnail, tap the text field that says “Add a description.” - Type and save
Enter your alt text. Tap the checkmark or back arrow to save. - Post
Tap the send icon. The app checks for missing alt text before posting.
Common Mistakes and Limitations When Adding Alt Text
Alt Text Field Does Not Appear After Upload
If you do not see the edit icon or the description field after uploading an image, refresh the page or restart the app. This issue sometimes occurs with older browser cache or a slow network connection. Clearing your browser cache for the Mastodon site usually resolves it.
Character Limit Exceeded
Mastodon caps alt text at 1,500 characters per image. If your description is longer, trim it to the most important details. Focus on who or what is in the image, the action, and any text that appears. You can add additional context in your main post text.
Alt Text Lost When Editing a Post
If you edit a post that already has images with alt text, the alt text may disappear in some older Mastodon versions. This is a known bug in versions prior to 4.0.0. After editing the post text, re-check each image and re-enter the alt text if it is blank. Upgrading your instance to the latest version prevents this issue.
Third-Party Apps Do Not Support Alt Text
Some third-party Mastodon clients, especially older or abandoned ones, do not provide a way to add alt text. If you use an app that hides the alt text field, switch to the official Mastodon app or to the web interface for posts that include images. You can still use the third-party app for reading your timeline.
| Item | Official Mastodon Web | Official Mastodon Mobile App |
|---|---|---|
| Alt text field location | Below image thumbnail after clicking pencil icon | Below image thumbnail after tapping edit or description label |
| Character limit | 1,500 characters per image | 1,500 characters per image |
| Warning before posting without alt text | Yes, with option to bypass | Yes, with option to bypass |
| Support for multiple images | Yes, each image gets its own alt text field | Yes, each image gets its own alt text field |
Adding alt text to every image you post is a small habit that makes the fediverse more inclusive. Start by describing one image per day, then scale up to all images. If you use a tool like IFTTT or a bot to post images automatically, check whether that tool supports alt text. Many automation tools strip alt text, so you may need to add descriptions manually after the post is created.