WordPress SmoothGallery Plugin

This WordPress plugin helps you to embed JonDesign’s SmoothGallery in your blog.

Basically it’s this simple:

  • upload some pictures to a post or page
  • use the shortcode smoothgallery
  • set some options
  • watch your smooth gallery

You can download the plugin here.


Have a look at this example. Kudos to my brother and his friends for taking these awesome pictures; thanks that I may show them here. They show different scenes from the Bergpark in Kassel, Germany.

Bergpark - Bridge

Another stunning picture.

Bergpark - Bridge

Bergpark - Aqueduct

Wow! That's awesome.

Bergpark - Aqueduct

I’m collecting real world examples where this plugin was used: if you’re interested have a look at the showcase page.

How to

Once you’ve activated the plugin you can start adding galleries to your posts and pages. I’ve split up this How to section into the following use cases.

Getting started

Adding a smooth gallery to a post or a page is easy! Try this:

  • go to the edit screen for a post or a page
  • right below the input field for the title click on Add an Image
  • upload some images and enter a sensible title and description
  • reorder the images however you want them
  • insert [smoothgallery] somewhere in the content
  • add a custom field named smoothgallery with its value set to On
  • hit save and click on View this Post/Page to see the result

If you’d like to customize the gallery check out the available options.

Activating the development version

If you’d like to use the latest version of SmoothGallery just activate it in the file config.php:

  1. add a # at the beginning of line 43 and 44
  2. remove the # from line 45 and 46

The plugin now uses the new version; currently SmoothGallery 2.1beta1 with Mootools 1.2.

iFrame it

Embedding the SmoothGallery inside an iFrame has several advantages:

  1. the JavaScript for SmoothGallery doesn’t interfere with incompatible frameworks like jQuery, PrototypeJS that you’re probably using on your site
  2. you can have more than one gallery on a single page

Just add iframe=1 as an attribute to the shortcode. If you’ve previously used the normal SmoothGallery and put all the options inside the custom field you’ll have to transfer these to the shortcode now. Say, you’ve got h:250 and i:false in your custom field then you would put this into the shortcode [smoothgallery iframe=1 height=250 showInfopane=false].

Note that you don’t need the custom field anymore; just remove it. Furthermore you can’t use the shortcuts, e.g. h for height, use the long version instead, i.e. height instead of just h. Finally you can’t even use : instead of = in the shortcode either.

More than one gallery

All you have to do is adding the shortcode [smoothgallery] several times to your content, with the iFrame option enabled. Have a look at the options on how to customize the appearance of the galleries.

If you don’t want to use iFrames for some reason have a look at this alternative solution.

A gallery in your sidebar or theme

I’ve created a separate page for this issue.

Some people want to do this because they’d like to have the images of the most recent posts inside a gallery; sometimes displayed in the header part of their theme. Read about this here.

Images from Flickr or Picasa

Your images are hosted on Flickr or Picasa and you want to show them inside a SmoothGallery on your blog? No problem, follow these two steps.

  1. Open the file config.php that comes with the plugin in an editor, search for ENABLE_FLICKR and ENABLE_PICASARSS and change the value from false to true for one of them or both. If you’d like to use Flickr make sure to supply your API key (FLICKR_APIKEY) and secret (FLICKR_SECRET) as well.
  2. Use the following attributes along with the shortcode:
    • flickrusername: supply your Flickr username and the most recent photos from your photo stream will be included in the gallery.
    • flickrphotoset: use this if you want to show images from a particular set of photos.
    • picasaurl: navigate to an album on Picasa, grab its RSS feed and supply it with this attribute in the shortcode.

Have a look at the examples to learn more about their usage.

In case you want to resize images on the fly there’s a parameter called imgmax that you can use. This parameter special to Picasa will resize the image to fit in the frame of SmootGallery. Here’s an example:

[smoothgallery iframe=0 width=640 height=480 embedLinks=false
 timed=true delay=6000 bordercolor=fff imgsize=640x480

Notice the imgmax parameter at the end of the picasaurl.

Using ReMooz to open the images

If you’ve linked to larger images in your SmoothGallery but don’t want them to open in a new window ReMooz comes to the rescue. Make sure to activate the development version first and keep in mind that this won’t really work if you’ve put SmoothGallery inside an iFrame.

Either add r:true to the custom field or add useReMooz=true as an attribute to the shortcode.

Generated thumbnails

If you’d like to use the carousel feature of SmoothGallery you’ll have to either generate thumbnails yourself or use the plugin to do this for you: just set ENABLE_GENERATED_THUMBNAILS in the file config.php to true. Furthermore make sure that the directory cache under smoothgallery/extra is read/writable by the webserver.

By default, the shortcode generates markup that contains a link for each image to its large version. This is great if you’d like to have a pure image gallery. If you’d like to setup a gallery, say, for your featured posts with a teaser image and a link to the corresponding post, you can do this like so:

  • go to Media Library
  • edit an image
  • supply a SmoothGallery link

and save. Once you’ve done that the image in the gallery uses the given URL.

For control freaks

If you’d like to have more control over the exact markup that gets inserted inside your page, maybe you don’t want to use the shortcode but insert everything yourself. I’ve prepared two starting points for you:

  1. under Advanced Options on the edit screen scroll down to SmoothGallery and use the generated HTML markup
  2. generate the markup with this tool

No matter what you’ll use, you’ll end up with some markup that you can start customizing. Check out all the available options for full flexibility.

You also might want to check out the tool box which has got useful wizards to ease the creation of compatible markup.


If you aren’t using iFrames and you don’t annotate your post or page with smoothgallery the CSS and JavaScript will not be loaded and the gallery won’t work. So, add a custom field with the key set to smoothgallery if you’d like to enable the SmoothGallery for a particular post or page. If the value is set to 1 or On the default values for the gallery will be used.

If you want to change the defaults you can use the following options. I’ve split up this section into options that come with SmoothGallery and the ones that I’ve added. It’s meant as a reference for you – so, if you’d like to change something you can look up the options here.

SmoothGallery options

Here are the most common options for SmoothGallery. If you need more: have a look at the top of the file utils.php that comes with this plugin.

Option Short version Default value
showArrows a, arrows true
showCarousel c, carousel false
showInfopane i, info, infoPane true
embedLinks l, links true
timed t false
delay d 9000

I added some more options that aren’t part of SmoothGallery. They help you to customize the dimensions and other CSS related parameters.

Option Short version Default value
height h 345
width w 460
bordercolor b, border 000

Example for the custom field

With the following code you would end up with a timed gallery that is set to 350×400 pixels and has got a white border. This goes into the custom field named smoothgallery:


As you can see, you can use : instead of = too. Mixing the long and short version of the attribute names is okay.


The shortcode [smoothgallery] has got some more attributes. If you’re using the attribute iframe along with the shortcode you can use all the above plus the following attributes. Currently the shortcuts that may go into the custom field, e.g. h for height, aren’t supported here – use the long version instead, i.e. height instead of just h.
Please don’t confuse the following with the options that you can use along with the custom field – the following attributes are solely for the shortcode.

By default the shortcode uses the images attached to the current post or page. If you’d like to use the images attached to another post or page you don’t have to upload them again but just specify the id of the specific post/page with this attribute.
Add this parameter if you’d like to take advantage of a gallery inside an iFrame.
Adapt the background color of the iFrame. Just supply the color code without the preceding #.
If you upload images with WordPress thumbnails will be created for you. We can try picking up these images instead of the original version with this parameter. Say, you’ve set the Thumbnail size for your images under Settings – Media to 150×150 pixels. If you add the parameter imgsize=150x150 to the shortcode the gallery will display the thumbnails instead of the originals.
flickrusername, flickrphotoset
Either just supply your Flickr username and the most recent photos from your photo stream will be included in the gallery or add the attribute flickrphotoset to show images from a particular set. Hint: when you click on a set in Flickr, in the URL it says /sets/numbers#: that number is the one you should use with flickrphotoset.
Navigate to an album on Picasa, grab its RSS feed, supply it with this attribute in the shortcode and the gallery will use your images from Picasa.
You just want to show some images that are in a directory on your webserver? Open the file config.php, add your directory to the array inside the function getImageDirectory and add the attribute dir to the shortcode pointing to the path in the array, i.e. dir=0 for the first path, dir=1 for the second one and so on.

Examples for the shortcode

On this very page I’m using the following simple shortcode to generate the markup for the SmoothGallery:

[smoothgallery imgsize=400x266]

This will grab the images that I uploaded to this page for the gallery. The attribute imgsize says, that I don’t want to use the images with their original size, but the thumbnails that were generated by WordPress during the upload process.
Alongside this shortcode I put this into the custom field named smoothgallery:


This makes sure that the width and height are set accordingly; that there’re no links to the large versions of the images; that it’s a timed gallery with six seconds between the transitions.

As you can see some options go into the custom field and others go into the shortcode. In case you’re adding the iframe attribute to the shortcode you have to supply all the options that originally went into the custom field in the shortcode; this is due to technical reasons and the way iFrames work.

If I wanted to use an iFrame instead, the above example would become (line break just for readability):

[smoothgallery iframe=1 width=400 height=266 embedLinks=false
               timed=true delay=6000 imgsize=400x266]

Note that you don’t need the custom field anymore; just remove it. Furthermore you can’t use the shortcuts, e.g. h for height, use the long version instead, i.e. height instead of just h. Finally you can’t even use : instead of = in the shortcode either.

The images for the gallery can be imported from virtually anywhere: Flickr, Picasa or a simple folder on your webserver just to name a few. If I wanted to show the images of my photo stream on Flickr I would use this shortcode:

[smoothgallery flickrusername=27834774@N05]

Just showing the photos of a particular set can be done using the flickrphotoset attribute. The same works with albums from Picasa: browse the albums there, copy the corresponding RSS feed and add it to the shortcode with picasaurl.

Confused ?

Are you confused because of all these options, attributes, parameters, shortcuts and shortcodes? Instead of getting angry at all this stuff please just stay relaxed, read the FAQ or add a comment with your problem to this page and I’ll try to come up with a sensible response.

Message from Certkiller We offer 642-436 training with braindumps that include custom design templates and other WP themes to help you pass 640-816 exams.


  • eahn says:
    Hi Christian, I was digging through the error log files but didn’t find much. I disabled some web security options and added set_time_limit(0) to the wp configuration file, but I’m still seeing the error- it’s actually gateway timeout error(visitor said internal server error, but I haven’t seen that yet). I find it strange because I only get it on slideshow whereas the rest of the site loads fine. Could it maybe having too many images in the slideshow?
  • Hi eahn,
    if it says “Gateway timeout error” the script might be loading too long and times out eventually. That said, the slideshow might indeed contain too many images. Even though I’ve never had this issue I recommend removing images from the gallery to see whether the error goes away.
  • eahn says:
    yeah I think you are right. Everything else loads fine, there is nothing wrong with the server, and when I make slideshow with fewer images, it loads pretty instantly and there is no extended waiting time that often leads to gateway timeout. Thanks for your plugin and tech support :)
  • Hello! I’ve installed the smoothgallery plugin, and it mostly works, except the slide show has all the images zoomed way in, so you can only see a small part of the image!

    Help please! :)

  • Hi Joshua,
    try using the imgsize attribute for the shortcode to select the images in the correct size. You can read more about that in the help section above. Once you’ve done that ideally the size of the SmoothGallery matches the widht and height of the images.
  • Well, I think I spoke too soon saying it was working. When I try to use the “shortcode” [smoothgallery], and also add the custom field shortcode = On, the plugin doesn’t see to work at all. I can get it to work with that zooming only when I copy the code from “smoothgallery” section down below on the edit post page. It should work without doing that, right? By just putting the images on the page and then putting in the shortcode?
  • Hi Joshua,
    you’re right: Inserting the shortcode and adding the custom field should be just enough to get started. Keep in mind though that by default the shortcode will pickup the default variants of the image, i.e. just the one you uploaded without any resizing applied. If you would like to select smaller versions generated by WordPress you’ll have to add said attribute (imgsize) to the shortcode.
    If the shortcode isn’t working at all you can try removing the custom field and adding the attribute iframe to the shortcode instead.
  • Wow, thanks for being there and trying to figure this out with me. I really want to use your plugin, I like it as it integrates so nicely with the post editing page.

    I tried removing the custom field and adding an iframe attribute to the shortcode, and still all I’m getting is a horizontal line and ALSO all the images are just showing up as usual in the post. :(

  • sven says:
    any option to put this in the theme directly? without shortcode in post?
  • Hi Sven,
    I recommend setting up a sidebar for this in the theme and using the widget that comes with the plugin.
  • sven says:
    anderen Weg gibts nicht? die Bilder pro Post auszulesen und im Theme dar zustellen? Ist nen Custom Theme ohne Sidebar & Widgets ;)
  • Hi Sven,
    da das Einbauen einer Sidebar so extrem leicht und in wenigen Minuten gemacht ist, habe ich genau in diesen Fällen immer den Weg gewählt. Im Plugin selbst habe ich keine besondere Funktion dafür vorbereitet, aber wenn Du dir den Code in den Dateien smoothgallery.php und utils.php anschaust, dann kannst Du sicherlich eine der Funktionen direkt aufrufen. Als Einstiegspunkt kannst Du dir zum Beispiel smoothgallery_shortcode() anschauen.
  • [...] worse than digging through the news posts. So, I thought I would gather them all here  in a nice gallery where anyone could flip through them like I do. I’ll be adding each new cover as issues are [...]
  • Aurélie says:
    He Christian, I think I managed to create a slideshow but when I go on the page, it’s loading, loading, loading…. there is a circle who goes round and round, and the slideshow never start. What can I do?
  • z says:
    The delay parameter doesn’t work. See here.

    These are the custom fields I use:

  • Hi z,
    if you’re entering the configuration via a custom field abbreviations might not work. That said you should use width instead of w, height instead of h and thus delay instead of d. This way the given delay should work as expected.
  • z says:
    thank you for your previous answer and i have 2 more please:
    1) is it possible to create a gallery with random image show ? how can i do this with custom field ?

    2) is it possible to re-use photos i already uploaded in previous posts ? or i need to re upload every time ?

    thanks a lot for the support ! really great

  • Hi z,
    regarding your questions:

    1. it isn’t possible to randomize the order of the images in the gallery with the plugin alone. In this case you would need some PHP code that outputs the HTML for the gallery which outputs the images in random order.
      Update: it is possible! Use, e.g., randomize=1 in the shortcode.
    2. see the id attribute for that matter.
  • Jon Howard says:
    Hi Christian. I have a couple of questions (although i am not a WP expert – I use the CMS at work to update a site built by someone else)

    1) I’ve just updated the plugin to 1.15.6. Previously, i could build a gallery from my media library (if i added content to a post and then deleted, it appeared in the gallery). This no longer seems to work. Is there a different way i should be doing this? I was never sure this was the right method anyway!
    2) Is there a way to delete images from a gallery without deleting from the media library.



  • Hi Jon,
    basically you add photos to a gallery by uploading images directly to the post / page the gallery should be on. When you use the shortcode in your content then the plugin automatically uses the images from the current post / page by default. If you stick to this pattern – one gallery per post / page and images uploaded to those posts / pages – you don’t have to worry about how these images are administered in the media library.
    Right now the plugin doesn’t have an exclude feature which means that you really have to delete images that shouldn’t be in the gallery anymore or at least detach the images in question from the post / page with the gallery.
  • z says:
    Hi Christian Schenk, when using :

    [smoothgallery randomize=1 ...]

    It is making the images random, I think you should add this to the documentation.

    I have one last question, is it possible to show thumbnails like here; look at top right of the gallery. I did not found how to enable this option.

  • Hi z,
    check out how to generate the thumbnails for this preview panel. Once you’ve done that the carousel should show up.
  • z says:
    thank you christian for all the great help. i have one more question please.
    my client is complaining that it takes to long for the page to load. it seems as if all the photos of the gallery are downloading and only then the slider starts.
    i am using IFRAME option with RANDOM show.

    is there anything that can be done ? (if i will switch it from iframe maybe it will load differently ?)

    thank a lot for everything !

  • Hi z,
    there are two options that may speed things up:

    1. move the JavaScript in the head section of the generated iFrame content; right now it’s in the footer. This way the JavaScript should be executed when the page gets loaded, show a loading images progress bar while the images are loaded in the background. This requires tweaking the PHP code of the plugin though.
    2. reduce the number of images in the gallery and optimize the images for a good quality/size ratio.
  • Jon Howard says:
    Christian, thx for your reply of Oct 7th.

    I have another couple of questions…

    1. Is there a way to add images that are already in my media library to a new gallery, rather than upload again – I want to avoid having multiple copies…or is there no way around this?
    2. Is it possible to have two different galleries in the same post containing different images?

    Thanks again.

  • Hi Jon,

    1. if you uploaded the images to a different post / page you can use the id attribute in the shortcode to use the images from that other post or page. Without editing the HTML markup yourself picking individual images and adding them to the gallery isn’t possible right now but planned for a future update.
    2. you can simply use the shortcode [smoothgallery] with the iFrame feature and the id attribute to use images from different posts or pages and display them on the same page in two or more galleries. If you want to have full control over this you can of course insert custom HTML into your website / theme – see my post on how to do this here.
  • z says:
    hi, i changed:
    add_action(‘wp_footer’, ‘add_smoothgallery_js’)

    add_action(‘wp_head’, ‘add_smoothgallery_js’)

    but this still don’t add a loading images to my gallery. can you please guide me some more on how to do this ?

  • z says:
    along with my previous message, i moved :

    in the file (utils.php) to the header of the iframe. but don’t see any loading indication.
    and the “carouselPreloader: true,” is on.

    how can i enable some kind of a loading indication on iframe ?

    thank you

  • Hi z,
    if these changes don’t make any difference this may be related to the way how browsers handle iFrames. Unfortunately, I don’t know how to resolve this right now but would have to make a few tests as well. I suggest you setup a simple test page which just holds the HTML, CSS and JavaScript for SmoothGallery and try to change this sample page to see what changes result in which behavior. Checking out the details of SmoothGallery and how it’s set up might help you debugging this.
  • rick says:
    Hi Christian,

    I am runiing WP 3.6.1 and something has recently ‘broken’ with your plug in, it effects the media library and the only clue i can find is that deactivating your plug in fixes the issue, i get this notice if i look at an image in the media library,
    Warning: Illegal string offset ‘image_meta’ in /home/galumayc/public_html/wp-content/plugins/smoothgallery/smoothgallery.php on line 298

    Warning: Illegal string offset ‘smoothgallery_link’ in /home/galumayc/public_html/wp-content/plugins/smoothgallery/smoothgallery.php on line 298

  • Hi Christian,
    Couple of questions.
    I migrated the site from my localhost on MAMP to the server. Obviously the links to the pictures were wrong. I tried deleting the short code, then putting the pictures back on the page from the library, then reinsert the short code. I get a message that says no pictures linked. Can’t figure out how to get around this.

    Also how do you add new pictures to an already existing gallery?

  • Hi Rick and Mike,
    @Rick: I just released an updated version (1.15.7) of the plugin which should fix the issues you describe. Thanks for the hint!
    @Mike: most likely you’ve uploaded the images via the media library directly and thus they aren’t associated with the post where you added the shortcode. Either associate the images with the post in question or upload the images via the “Add media” link when editing that particular post. If you then want to add images to a gallery simply upload the images to the post and they will automatically appear in the gallery.

Leave a Comment

Hint: consider reading the FAQ before submitting a question.