HTML5 Galleries in WordPress 3.9

With the new release of WordPress will come the ability to declare support for HTML5 markup in galleries. Once a theme declared support, the definition list elements will be replaced by <figure> and <figcaption> for better semantics.

If you decide to not only adopt this new feature but also maintain backwards compatibility, then there are two ways to achieve that:

  1. Style not only the new HTML5 elements, but also add CSS selectors for the traditional definition list elements. This is the route we chose for _s to keep it as simple as possible.
  2. Filter the shortcode attributes and override the tag parameters. Since the shortcode_atts_gallery filter was introduced in 3.6, you’ll be backwards compatible with the latest two versions.

The callback to override the tag parameters could look something like this:

 * Replaces definition list elements with their appropriate HTML5 counterparts.
 * @param array $atts The output array of shortcode attributes.
 * @return array HTML5-ified gallery attributes.
function prefix_gallery_atts( $atts ) {
	$atts['itemtag']    = 'figure';
	$atts['icontag']    = 'div';
	$atts['captiontag'] = 'figcaption';

	return $atts;
add_filter( 'shortcode_atts_gallery', 'prefix_gallery_atts' );

This second way of adding backwards compatibility has the added benefit that it also adds forward compatibility, as you’re able to use HTML5 markup for galleries now, even before WordPress 3.9 will be released in April.

Please keep in mind that WordPress  will no long output its default gallery styles by default, when HTML5 support for galleries has been added.

Author: Konstantin Obenland

Release Lead (Ret.) at Automattic, WordPress Contributor. Can be found on Twitter (@obenland).

21 thoughts on “HTML5 Galleries in WordPress 3.9”

  1. We talked briefly about this at Wordcamp Phoenix this year; I’m so excited to see it coming to fruition in core in 3.9! Yay!

  2. Filter the shortcode attributes and override the tag parameters looks better methond among these two methods.

  3. Awesome! Do you know if there will be a way to remove the “ tags that get inserted in galleries?

  4. Sorry, thought I could post code – the tag I meant was br style=”clear:both;”

      1. Ah! I got stuck in WordPress forum backtick-code land, sorry. 🙂 I’ve submitted a comment on that ticket. Thanks!!

  5. Some folks might be concerned about styling the new markup so I pasted some simple code to make things look reasonable.

    1. There’s an open pull request about that at and it looks like there’s some ongoing discussion about adding caption styles alongside that change. Might be a good time to take another look now that WordPress 3.9 has been released. Chime in on the PR if you have ideas about the best way to handle the corresponding styling.

Comments are closed.