tetchi blog

Tetchi's blog about life and stuff

Shopify Tutorial: Easy Captions for Images in Blog Posts and Pages using Alt Text

Shopify Tutorial – learn how to automatically generate captions for your pages and blog articles using alt text.

In this tutorial, we’re going to write some script that will automatically generate captions for images on blog posts and pages in Shopify using the image’s alt tag.

I wrote this quick tutorial because I was seeing a lot of questions in the forums about how to captions to blog posts. Instead of having customers add captions manually (which would require knowledge of HTML/CSS), I think this method is a lot easier as you can just insert alt text to images through the RTE.

You can see a demo of this here.

caption demo

How it works

The script works by checking the alt text of every image in a blog article of page. If that image has an alt tag, the script will wrap the it in an <figure> tag and append a <figcaption> tag containing the alt tag of the image.

We’re also going to be adding some nice theme settings to spice up the captions :)

caption settings

Let’s get started!

Adding alt text to an image

If you’re unsure of how to add alt text via the RTE, here’s a quick refresher.

Go to a page or blog article, and in the RTE click Insert > Image. Browse your computer for an image of your choice and click the “Insert Image” button.

caption edit

Once you’ve added the image, click on it and you’ll see a little “edit” link at the bottom. Click on “edit” to open up that image’s options. You can then enter some text to describe the image in the “Description” field. This becomes the alt text of the image.

figcaption alt text

1. Wrap the page and/or article content with a unique div

The first step is to wrap the RTE content with a div that has a unique class so that we can target it with jQuery. It’s up to you whether you want the captions to show in the blog articles *and* pages. Refer to the list below to see which Liquid variable you need to look for in which template.

  • page.liquid – {{ page.content }}
  • blog.liquid – {{ article.content }}
  • article.liquid – {{ article.content }}

We’re going to be wrapping the page/article content with a special div class called “caption”. Below is an example of wrapping the page content in page.liquid of the Radiance theme.


{{ page.content }}


{{ page.content }}

2. Add the jQuery and CSS Snippet

Create a new snippet called “captions”. Add the content of this gist.

At the bottom of theme.liquid, you should see a closing </body> tag. Right above it, place the following code in red:

{% include 'captions' %}

What this script does is it looks at the alt text of all images within divs with the class “caption”, and first checks if it’s blank or not. If it isn’t, it will wrap the image in a <figure> tag and append a <figcaption> tag containing the alt text of the image.

3. Add in the Theme Settings for the Captions

Locate “settings.html” in your Template Editor. At the very bottom, paste the code from this gist. Hit Save.

If you go to your Theme Settings, you should see new settings for styling the captions. Adjust the settings to your liking and hit “Apply Changes”.

That’s it!

That’s it that’s all. You should now see the alt tags of your images shown below your RTE content’s images. Hope this helps!



  • Michael
    Michael on May 30th, 2013

    I notice this will only work when you do not wrap the text around the image. Otherwise it pushes you caption above the text. Any ideas on how to get around this. I really like the concept.

  • tetchi
    tetchi on May 31st, 2013

    I’m not sure if I follow. Do you have an example you can show me?

  • Michael
    Michael on May 31st, 2013

    If you could email me I can provide screen shots. But I can try to explain a little better. I followed the steps as you outlined and the captions appear. However, In your example the picture is centered and the caption appears below as it should. For me, I like to align my photos to the left and then wrap the text around the picture. When I do this, the caption to my picture appears above the above the page text instead of below the picture. The code for the incorrect page appears like this

    ladies…so not everyone has the privilege of having King Dong in their bedroom
    night after night.  But that’s not
    necessarily a bad thing.  For every guy that

    However if I do not wrap the text around the image the caption appears as it should. Also is there a way to decrease the space between the caption and the Picture?

  • allison
    allison on October 22nd, 2013

    Hi – I am wondering if you have any updates on the align left/right and the captions. Same thing – it works great if the images are centered on the page.


  • Casey
    Casey on October 30th, 2013

    I am trying to make it so that when you click on an image within a table on a page the alt text shows up as a caption on the expanded image. I’ve followed these instructions but the captions are still not showing up. I can see the caption setting in the theme settings but nothing on the pages.

    I am not a web developer and I am in a bit over my head.

    Any help is much appreciated.


  • Theresa
    Theresa on October 22nd, 2014

    Hi if you don’t add a description you get undefined how to make it conditional?

  • Susan
    Susan on January 12th, 2015

    I too have an image I need to put a caption under, but all of the paragraph text in the blog wraps around the image. Do you have a script for that?

    best regards

  • Matthew Thomson
    Matthew Thomson on April 28th, 2015


    I’m attempting to implement this tutorial using the Parallax theme to add captions to images added with the RTE.

    I’ve managed to display the alt tags, however they don’t want to sit under the images, but rather align with the text that wraps around the image?

    Is it possible to modify the snippet so that it creates a rather than the which I could then use to wrap the img and alt tag so they display correctly?


    Matt Thomson

  • McKenna
    McKenna on August 18th, 2015

    Wow, Tetchi, this is exactly what I needed! Only issue is that I can’t get the last gist (to adjust the theme settings) to work. I get a huge error message when I try to save it. Granted they’ve updated Shopify a bit since this but do you have any suggestions? I’m using the Atlantic theme…at least I think I still am. Had some modifications made but I’m code-illiterate (hanging on by my fingernails!) so not totally sure.. thanks!

  • Emily
    Emily on February 11th, 2016

    Hi, I’m having issues with the last step-I can’t find settings.html in the Template Editor. Would you be able to direct me to where I can find it?

    Thank you!

  • Emily
    Emily on February 11th, 2016

    Hi, I don’t have a settings.html file for my Shopify theme, but I do have a json file-one called settings_data.json and another called settings_schema.json.

    Do I need to translate the GIST code from step 3 into JSON for this to work?

    Thank you!

  • tetchi
    tetchi on February 15th, 2016

    Hey there Emily, apologies for the late reply.

    Quite a lot has changed with theme settings since I wrote this in 2012 – theme settings are now pulled from a JSON file called settings_schema.json and not settings.html. More info here: https://docs.shopify.com/themes/theme-development/storefront-editor/settings-schema

Post a comment