# SmartAlt > Full documentation content for SmartAlt --- # Default ## Getting started ### Overview **URL:** https://smartalt.mantledocs.com/overview In this area, you’ll find guidance on how to install and configure SmartAlt for use. --- ## Features ### Features Overview **URL:** https://smartalt.mantledocs.com/features-overview In this area, you’ll find guidance on the available features within SmartAlt and how to use them. --- ### Generate alt text manually **URL:** https://smartalt.mantledocs.com/generate-alt-text-manually ## Overview If you want to update product image alt text manually in SmartAlt, use the **Generate Alt Text** screen inside the app. This lets you choose all listed images or only specific ones, then generate alt text in bulk. In Shopify admin, open **Apps** → **SmartAlt - AI Alt Text** → **Generate Alt Text**. ## Generate alt text from the app menu In the left navigation, go to **Apps** → **SmartAlt - AI Alt Text** and click **Generate Alt Text**. You’ll land on a page titled **Generate Alt Text** showing your store media in a list. On the **Generate Alt Text** page, each row shows an image thumbnail and its **Current Alt Text**. Use the **View** button on the right if you want to inspect an individual item before generating new text. ![SmartAlt Generate Alt Text screen showing the All Store Media list, selection checkboxes, Current Alt Text column, and Generate Alt Text button](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/81f7f89f-bed5-4106-b2ad-0fb58ed10d0a/Screenshot_2026-04-01_at_12.53.27.png) Tick the checkbox beside each image you want to update. - To update individual items, tick only those rows. - To update everything currently listed, use the top checkbox to select all visible rows. - If SmartAlt shows the link **Select all images across all pages**, click it to include the full result set instead of only the current page. After making your selection, click **Generate Alt Text** in the top-right corner. The button label may show the number of selected images, such as **Generate Alt Text for 1 Image**. When generation finishes, review the list again to confirm the **Current Alt Text** has been updated for the selected images. You can use **View** on any row to inspect individual results. ## What to expect on this screen - **All Store Media** shows the images SmartAlt can process. - **Add filter +** helps narrow the list before you select images. From this menu you can select images without an existing alt tag. - **Current Alt Text** shows the existing or newly generated alt text for each image. - **View** opens the item so you can review it more closely. If you only want to update a small set of products, select individual rows instead of running generation for the full list. ## When to use this method This manual workflow is useful when you want to: - update alt text for a specific group of images, - review existing alt text before regenerating it, - run alt text generation on demand instead of relying on automation. ## Related workflows Filter products in Shopify first, then send the right selection to SmartAlt with Manage with SmartAlt. Use Specific metafields in Settings to control which product details SmartAlt uses in generated alt text. --- ### Generate alt text automatically **URL:** https://smartalt.mantledocs.com/automate-alt-text-generation ## Overview SmartAlt can generate missing alt text automatically in the background. You can turn automation on from the **Settings** screen and choose when SmartAlt should run. In Shopify admin, open **Apps** → **SmartAlt - AI Alt Text** → **Settings**. Use automation when you want SmartAlt to handle missing alt text without starting a manual run from the **Generate Alt Text** screen. ## Turn on automation In Shopify admin, go to **Apps** → **SmartAlt - AI Alt Text**, then click **Settings** in the left navigation. On the **Settings** page, find the **Automation** section. In **Automation**, select one of these options: - **Full auto mode (processes all images with missing alt text)** — scans your store and generates alt text for images that do not already have alt text. - **Creating a Product** — generates alt text when you create a new product. - **Creating / Updating a Collection** — generates alt text when you create or update a collection. After selecting the options you want, click **Save** at the top of the page. Your automation preferences will be applied after saving. ![SmartAlt Settings page showing the Automation section with Full auto mode, Creating a Product, and Creating / Updating a Collection options](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/eb321869-ade4-4d16-b6ba-eb71dfa1e5c4/Screenshot_2026-04-01_at_12.59.51.png) ## What each automation option does ### Full auto mode Choose **Full auto mode (processes all images with missing alt text)** if you want SmartAlt to work through your store’s existing images that are still missing alt text. ### Creating a Product Choose **Creating a Product** if you want alt text generated as part of your new product workflow. ### Creating / Updating a Collection Choose **Creating / Updating a Collection** if you want SmartAlt to run when collection content changes. ## How automation fits with manual generation Automation handles generation for the events you enable in **Settings**. If you ever want to run alt text generation yourself, you can still use **Generate Alt Text** from the SmartAlt menu to review media and start a manual run. Use the Generate Alt Text screen to select images and run alt text generation on demand. Use Specific metafields in Settings to guide what SmartAlt includes in generated alt text. Filter products in Shopify first, then use Manage with SmartAlt for a targeted run. --- ### Include product details in alt text **URL:** https://smartalt.mantledocs.com/include-product-details-in-alt-text ## Overview SmartAlt can include product information in the alt text it generates for product images. From the **Settings** screen, you can choose whether SmartAlt should use the **vendor name**, the **product title**, and any **specific metafields** associated with the product. This is useful when you want alt text to reflect the product data already stored in Shopify, instead of relying only on the image itself. ![SmartAlt Settings showing the Alt Text preferences section with Include vendor name, Include product title, and Specific metafields options](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/2eccc89d-194f-4d80-b008-ccae4889e103/Screenshot_2026-04-01_at_13.16.11.png) ## Where to find these settings In your Shopify admin, open **Apps** → **SmartAlt - AI Alt Text**, then click **Settings** in the left-hand navigation. On the **Settings** page, scroll to the **Alt Text preferences** section. In this section, SmartAlt shows these options: - **Include vendor name** - **Include product title** - **Specific metafields** ## Choose what SmartAlt should include Go to **Apps** → **SmartAlt - AI Alt Text** → **Settings**. Scroll to the **Alt Text preferences** section. Tick any of the following checkboxes, depending on what you want included in generated alt text: - **Include vendor name** - **Include product title** - **Specific metafields** Click **Save** at the top of the page to apply the new preference. ## What each option does ### Include vendor name When **Include vendor name** is selected, SmartAlt can use the product's vendor as part of the generated alt text. This is helpful if the brand or maker is important context for your catalog. ### Include product title When **Include product title** is selected, SmartAlt can pull wording from the product title into the generated alt text. This can help keep alt text aligned with how products are named in your store. ### Specific metafields When **Specific metafields** is selected, SmartAlt can use content from selected product metafields as part of generation. This is useful when important descriptive details are stored in metafields rather than in the title. If you want SmartAlt to include custom product attributes such as material, style, finish, or other catalog-specific details, **Specific metafields** is the best option. ## Using multiple options together You can select more than one option in **Alt Text preferences**. For example, SmartAlt can use both the **product title** and the **vendor name**, or combine those with **Specific metafields**. This gives you more control over how much product context is included in generated alt text. ## Best practices - Use **Include product title** if your product titles are clear and descriptive. - Use **Include vendor name** when brand information matters to shoppers. - Use **Specific metafields** for product details that are not consistently included in titles. - Review your **Alt text character limit** if you enable several options at once. ## Frequently asked questions Yes. In **Alt Text preferences**, you can select any combination of **Include vendor name**, **Include product title**, and **Specific metafields**. Yes. After updating the checkboxes in **Alt Text preferences**, click **Save** at the top of the **Settings** page. If SmartAlt shows **No metafield definitions found**, your Shopify product metafield definitions may not be set up yet. Create them in Shopify first, then return to SmartAlt. --- ### Adjust alt text length **URL:** https://smartalt.mantledocs.com/adjust-alt-text-length ## Overview SmartAlt lets you control how long generated alt text can be. If you want shorter or longer descriptions, update the **Alt text character limit** in the app’s **Settings** screen. In Shopify admin, open **Apps** → **SmartAlt - AI Alt Text** → **Settings**. In the **Alt Text preferences** section, you can set the character limit anywhere from **100** to **256** characters. The default value is **125**. Use a lower limit if you want shorter, tighter alt text. Use a higher limit if your product images need more detail. ## Change the alt text character limit In Shopify admin, go to **Apps** → **SmartAlt - AI Alt Text** → **Settings**. The **Settings** page includes sections such as **AI Configuration**, **Automation**, and **Alt Text preferences**. Scroll to the **Alt Text preferences** section. This area also includes options like **Include vendor name**, **Include product title**, and **Specific metafields**. ![SmartAlt Settings showing the Alt text character limit field in Alt Text preferences](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/de8fc9d2-f058-471f-84b0-faa6e93379f5/Screenshot_2026-04-01_at_13.23.21.png) In the **Alt text character limit** field, type the maximum length you want SmartAlt to use when generating alt text. - **Minimum:** 100 characters - **Maximum:** 256 characters - **Default:** 125 characters Below the field, SmartAlt shows the guidance text: **Recommended: 125 characters (Min 100, Max 256)**. Click **Save** at the top of the **Settings** page to apply the new limit. Once saved, SmartAlt will use this character limit for future alt text generation. ## What this setting affects The **Alt text character limit** affects new alt text generated by SmartAlt. This applies when you run generation from the app’s **Generate Alt Text** screen or from Shopify using **Manage with SmartAlt**. - On the **Generate Alt Text** screen, SmartAlt uses your saved settings when you click **Generate Alt Text**. - If you select products in Shopify and use **More actions** → **Apps** → **Manage with SmartAlt**, the same saved character limit is used for that generation run. Changing the limit affects future generated alt text. It does not automatically rewrite alt text that has already been generated. ## Tips for choosing the right length - Choose a shorter limit if you want more concise alt text across large product catalogs. - Choose a longer limit if your images need more descriptive detail, especially when products include multiple visible attributes. - If you also enable **Include vendor name**, **Include product title**, or **Specific metafields**, a higher limit can give SmartAlt more room to include those details naturally. If your generated alt text feels too brief or too detailed, adjust the **Alt text character limit**, save the change, and then run **Generate Alt Text** again for the images you want to update. ## Related pages Select images on the Generate Alt Text screen and run alt text generation on demand. Use Specific metafields in Settings to control which product details SmartAlt includes in generated alt text. --- ### See Usage Reports **URL:** https://smartalt.mantledocs.com/usage-reports ## Overview The **Usage Reports** screen gives you a request-by-request history of work completed in SmartAlt. You can use it to confirm when a request ran, how many images were processed, where the request was generated from, and whether it finished successfully. This can be useful when tracking your usage for your selected plan. If you need to know which products were included in a specific request, use **View Items**. This opens a detailed list showing each product image in the request, the **AI Generated Alt Text**, and the item-level **Status**. ![Usage Reports screen showing request history, Images Processed, Generated from, Status, and View Items](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/09d7de1d-0b38-4658-8b6b-c8cf5aacd3e5/Screenshot_2026-04-01_at_13.33.11.png) ## What you can see in Usage Reports Each row in **Usage Reports** represents one SmartAlt request. The table includes the following columns: - **ID**: The request number for that run. - **Date**: When the request was created. - **Images Processed**: How many images were included and processed in that request. - **Generated from**: Where the request started, such as **SmartAlt App**, **Product List**, or **Manual**. - **Status**: The overall result of the request, such as **Complete**. If a request includes a **View Items** button, you can open it to review the products and alt text generated for that run. ## See which products were included in a request Go to the **Usage Reports** screen in SmartAlt. Review the table by **Date**, **ID**, **Generated from**, or **Status** to locate the request. Click **View Items** on the right side of the request row. On the request details screen, review each image, the **AI Generated Alt Text**, and the item-level **Status**. ## What appears in View Items When you open a request, the details page shows the individual items included in that request. This view helps you confirm exactly which products were processed and what SmartAlt generated for each one. On this screen, you can review: - **Image**: A thumbnail preview of the product media item. - **AI Generated Alt Text**: The alt text SmartAlt created for that image. - **Status**: The result for that individual item, such as **Successful**. - **View**: Opens the media item so you can inspect it in more detail. ![Request details screen showing Image, AI Generated Alt Text, Status, and View buttons](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/c73d432a-dddd-4b4b-942e-1fed1a99d812/Screenshot_2026-04-01_at_13.34.11.png) ## Use the View button for item-level detail Click **View** next to an item to open that media item individually. This is useful when you want to compare the generated alt text against the specific image, or verify the outcome for one product without reviewing the entire request. Use **Usage Reports** when a customer asks, “Which products were included in that SmartAlt run?” It is the quickest place to confirm both the request summary and the exact item list. ## Filter the request list The **Usage Reports** screen includes an **Add filter +** option at the top of the page. Use this when you need to narrow the list before opening a request. This can be helpful if you are looking for a specific request based on when it ran or when you want to focus on a smaller set of report entries. --- ## FAQs ### FAQs Overview **URL:** https://smartalt.mantledocs.com/faqs-overview In this area, you’ll find some commonly asked questions about SmartAlt functionality and features. --- ### What do I do if I've run out of credits? **URL:** https://smartalt.mantledocs.com/alt-text-credit-faq ## Overview If you run out of credits for applying alt text in SmartAlt, you have two options. - **Wait for your monthly refresh:** Credits refresh monthly, so if you are happy to wait, you will get access to more credits when the **1st of the month** arrives. - **Contact support for more credits sooner:** If you do not want to wait until next month, contact support and the team can manually add more credits for you. Alt text generation will pause once your available credits have been used up. You can continue again after your credits refresh on the 1st of the month or after support manually adds more credits to your plan. You do not always need to contact support. If you are happy to wait, your credits refresh automatically each month on the 1st. ## How to contact support If you need more credits before the next monthly refresh, contact the SmartAlt support team. Please note: Requesting more credits be added by the VS Labs team will incur an extra cost per credit. A final price will be given for any credits to be added, so you can sign off on it before the team goes ahead with adding the credits! Go to the SmartAlt Helpdesk. Use the **Live Chat Support** button in the top-right corner of the page. You can also open the support widget directly from the help page. Inside the widget, either start a live chat or send an email. Both options are available in the same place. Let support know that you have run out of credits for applying alt text in SmartAlt and would like more credits added manually. If you only need to continue next month, you can simply wait for the automatic refresh on the 1st instead of contacting support. ## Where this affects SmartAlt You may notice this while using the following areas of SmartAlt: - **Generate Alt Text:** Used when you select images and run alt text generation manually. - **Usage Reports:** Used to review previous requests, images processed, and request status. If a request cannot continue because you have used all available credits, check whether you want to wait for the next monthly refresh or contact support to add more credits sooner. ## FAQ If you run out of credits, you can either wait for your credits to refresh automatically on the **1st of the month** or contact support if you need more credits before then. Open the SmartAlt Helpdesk and click **Live Chat Support** in the top-right corner. You can also use the support widget on the page to contact the team by live chat or email. No. If you are happy to wait, your credits refresh monthly and you will get access to more credits when the 1st of the month arrives. Contact support only if you need more credits sooner. Tell the team that you have run out of credits for applying alt text in SmartAlt and need more credits added manually so you can continue before the next monthly refresh. ## Related pages Use the Generate Alt Text screen to select images and run a manual alt text request. Review previous SmartAlt requests, images processed, and request status. --- ### How to edit with SmartAlt directly from the product catalogue **URL:** https://smartalt.mantledocs.com/filter-products-before-using-smartalt ## Overview If you’re trying to organize or narrow down products inside the SmartAlt dashboard, you may notice there aren’t many filtering options available there. The recommended workaround is to filter products in Shopify first, then send the filtered selection to SmartAlt using **Manage with SmartAlt**. **What this achieves:** you can use Shopify’s built-in product filtering (such as **Status** and **Categories**) to precisely choose which products SmartAlt will process. ## Walkthrough: filter in Shopify, then manage with SmartAlt In your Shopify admin, go to **Products**. This is where you can view your full catalog, including columns like **Status**, **Inventory**, and **Category**. ![Shopify admin Products page showing product list with Status, Inventory, and Category columns](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/video-frames/27d048ff-881c-42da-9b24-ecd8aa2c4bef/frame_001.jpg) Use the filter bar to narrow the list. Open the **Statuses** filter and select the statuses you want (for example: **Active**, **Draft**, **Archived**, or **Unlisted**). ![Statuses filter dropdown open on Shopify Products page](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/video-frames/69ab5556-34a4-4b95-bea9-94513cbe6922/frame_002.jpg) If you use the same filters regularly, you can save them using **Save as** on the right side of the filter bar. Open the **Categories** filter and tick one or more categories to include. Shopify will update the product list to match your selections. ![Categories filter dropdown open on Shopify Products page](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/video-frames/0dc8daab-c62d-4514-85ef-255d9e5a358e/frame_003.jpg) Review the list and make sure it only shows the products you want SmartAlt to manage. You should see your selected filters (for example, **Statuses: Active** and **Categories**) applied above the table. ![Shopify Products list filtered by Status and Categories](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/video-frames/e5f116e5-2457-4264-a755-c1ae44f6b5b4/frame_004.jpg) Select the products you want to send to SmartAlt (using the checkboxes). Then open the **More actions** menu (the **…** menu) and, under **Apps**, choose **Manage with SmartAlt**. ![More actions menu open on Shopify Products page with “Manage with SmartAlt” highlighted](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/video-frames/919e3874-39e1-4f96-a10b-8c3075e29381/frame_005.jpg) If you don’t see **Manage with SmartAlt**, confirm SmartAlt is installed and you’re selecting at least one product. A confirmation modal opens titled **Manage with SmartAlt**. Review the message and click **Generate Alt Text** to start generating alt text for the selected products. ![Manage with SmartAlt confirmation modal with Generate Alt Text button](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/video-frames/4c429e12-1c57-4e02-abc4-da1f9c0e43f8/frame_006.jpg) Alt text generation applies to the products you selected in Shopify. Double-check your selection before clicking **Generate Alt Text**. You’ll be taken to SmartAlt’s **Generate Alt Text** screen, where you can review generated results in a list (with an image preview and the **Current Alt Text**). Use the **View** button on a row to inspect individual items. ![SmartAlt Generate Alt Text results page showing generated alt text list with View buttons](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/video-frames/4362ff61-8d41-45b8-bb24-655cdc9b241c/frame_007.jpg) ## Why this is the best workaround - **Shopify filtering is more flexible** than SmartAlt’s dashboard filters for organizing products. - **You stay in control** of exactly which products are included by filtering first and then selecting only what you need. - **It’s repeatable** —save filter views in Shopify for recurring SmartAlt runs (for example, specific categories or statuses). Use the filters available on Shopify’s **Products** page. In the walkthrough, the selection is narrowed using **Statuses** and **Categories**. You can also use other Shopify product filters available in your store’s admin (for example, vendor or tag), then send the resulting selection to SmartAlt via **Manage with SmartAlt**. No. The SmartAlt flow shown here is focused on generating **image alt text**. Your Shopify product organization (status, category, etc.) remains managed in Shopify. --- ### How to control alt text with Metafields **URL:** https://smartalt.mantledocs.com/control-alt-text-with-metafields ## Overview At this time, SmartAlt doesn’t offer a “suppress these words only for certain product types” setting (for example, hiding specific terms for mugs but keeping them for hats). The recommended workaround is to **control what SmartAlt is allowed to use** by providing product-type-specific wording in Shopify **metafields**, then telling SmartAlt to use those metafields via **Specific metafields** in **Settings**. **What this achieves:** instead of trying to block words after SmartAlt generates them, you provide the *approved words* per product type—so SmartAlt uses only what you’ve supplied. ## 1) Start from the SmartAlt Dashboard In your Shopify admin, open **Apps** → **SmartAlt - AI Alt Text**. The **Dashboard** gives a quick overview of your image coverage, including cards like **Total Images**, **Images without Alt Text**, and **Alt Text Coverage**. ![SmartAlt Dashboard showing Total Images, Images without Alt Text, and Alt Text Coverage](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/video-frames/94435906-9e0a-4129-92a7-9501bc0e293d/frame_001.jpg) ## 2) Turn on “Specific metafields” in Settings From the SmartAlt left navigation, click **Settings**. In **Alt Text preferences**, enable **Specific metafields**. When enabled, SmartAlt will look for the metafield key(s) you provide and use that content as an input when generating alt text. Go to **Apps** → **SmartAlt - AI Alt Text** → **Settings**. Scroll to **Alt Text preferences** and tick **Specific metafields**. In the metafield key field that appears under **Specific metafields**, enter the key for the metafield you want SmartAlt to use. In the walkthrough, this is where a metafield key is entered after turning on **Specific metafields**. Click **Save** at the top of the Settings page. ![SmartAlt Settings showing Alt Text preferences with Specific metafields enabled](https://cdn.heymantle.com/orgs/c60dabf2-e049-400a-a45b-5abda837631d/docs-pages/video-frames/71b62b9e-6225-4a78-91d5-914f4f623ebd/frame_002.jpg) If you also use **Include vendor name** and/or **Include product title**, keep your metafield wording short and consistent so the final alt text stays within your **Alt text character limit**. ## 3) Create metafields for each product type (Shopify) Next, create Shopify metafields so you can store the **approved words** per product type/category. The workflow used in the workaround is: - **Create one metafield per product category** (or product type), - Put the **words you DO want to appear** in that metafield, - Assign it on the product so SmartAlt can read it. The exact location of metafield creation in Shopify can vary depending on your admin version, but you’ll be creating metafield definitions for **Products** and then filling those fields on each product. ### Recommended naming approach Use a clear naming pattern so your keys are easy to manage. For example: - `alt_text_words_baseball_caps` - `alt_text_words_mugs` - `alt_text_words_tshirts` SmartAlt uses the **metafield key** you enter in **Settings**. If the key is mistyped (or the metafield isn’t assigned to the product), SmartAlt can’t use it during generation. ## 4) Fill in the metafield values on products Open a product in Shopify and set the metafield value for that product’s category/type. This is where you place the approved wording you want SmartAlt to use (for example: “stainless steel water bottle”, “navy branded baseball cap”, etc.). Keep the metafield text focused on what matters for accessibility: what the image shows. Avoid keyword stuffing—alt text should be descriptive first. ## 5) Generate alt text using SmartAlt Once **Specific metafields** is enabled and products have metafield values, generate alt text as you normally would: - In SmartAlt, go to **Generate Alt Text** to run generation and review results. - Or, from Shopify’s **Products** list, select products and use **More actions** → **Apps** → **Manage with SmartAlt**, then click **Generate Alt Text**. ## How this “suppresses” words in practice This approach doesn’t remove words from existing alt text automatically. Instead, it prevents unwanted words from being introduced by making the alt text input **product-type specific**: - If a product type should **not** mention a certain term, simply **don’t include it** in that product type’s metafield value. - If another product type **should** include it, include it only in that metafield value. You can reuse the same metafield key/value strategy across products. If you don’t need different wording per category, use a single metafield definition and populate it consistently across all relevant products. This usually means Shopify doesn’t yet have a product metafield definition available (or it hasn’t been created/assigned in a way SmartAlt can detect). Create the product metafield definition in Shopify first, then return to SmartAlt **Settings** and try again. The workaround described here is focused on controlling wording for **product images** by storing approved text on the product via metafields, then letting SmartAlt use it during generation. --- ## Troubleshooting ### Troubleshooting Overview **URL:** https://smartalt.mantledocs.com/troubleshooting-overview In this area, you’ll find guidance on troubleshooting for functionality and features within SmartAlt. ---