HTML5 Galleries & Captions in WordPress 3.9

WordPress 3.6 introduced HTML5 versions of popular template tags, starting out with comments, the comment form, and the search form. With the 3.9 release we add galleries and captions to that list. Now, when adding HTML5 support for those features, WordPress will use <figure> and <figcaption> elements, instead of the generic definition list markup.

To declare that your theme supports these new HTML5 features, add the following call to your theme’s functions.php file, preferably in a callback to the after_setup_theme action:

add_theme_support( 'html5', array( 'gallery', 'caption' ) );

For forward compatibility reasons, the second argument with the specific parts can’t be omitted when registering support. Otherwise a theme would automatically declare its support for HTML5 features that might be added in the future, possibly breaking its visually because of it.

For both galleries and captions not only the markup changes when a theme declares its support for them, there are also peripheral changes that come with it.


By default, galleries will not include inline styles anymore when in HTML5 mode. This caters to the trend of disabling default gallery styles through the use_default_gallery_style filterFilter Filters are one of the two types of Hooks They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., a filter that even the last two default themes used. With that, theme developers can always start with a clean slate when creating their own set of gallery styles.

We also took the opportunity to remove the line breaks between rows of images. Not only did they encourage an inferior way of positioning elements, more importantly they were non-semantic htmlHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. elements that are meant for presentational use, and they made it harder to style galleries.


Up until now, captions received an additional 10 pixels of width, to keep text flowing around the caption, from bumping into the image. As @nacin put it, this has vexxed theme developers for years, and even resulted in the addition of a filter in WordPress 3.7 to manipulate the caption width.

We were not able to completely remove the inline style in HTML5 mode, it’s still necessary to force captions to wrap, but we’re no longer the adding 10px of width. We also removed caption styles in the editor, bringing it on par with how non-captioned images are displayed:

Twenty Thirteen and Twenty Fourteen have been updated to support both features, while retaining backwards compatibility with older WordPress versions. There is a remote possibility however, that child themes that use element selectors to overwrite gallery or caption styles can lose those customizations. Please test your child themes with the current development versions of the last two default themes.

If there are any questions about the current implementation, feel free to leave a comment below.

#3-9, #dev-notes, #editor, #gallery, #html5, #themes