Here are two ways to include HTML5 elements in your WordPress post content without WordPress’ wpautop function wrapping them in p tags or littering your code with line breaks.

HTML5 has several new elements that you may want to use in your post content to markup document sections, headers, footers, pullquotes, figures, or groups of headings. One way to safely include these elements in your posts is simple; the other way is a bit more complicated. Both ways rely on hand-coding the HTML5 markup in the WordPress editor’s HTML view.

If you are adding HTML5 elements to your post content then you should use an HTML5 doctype.

Disable wpautop for your theme

This is the simple way. Disable the wpautop function so that WordPress makes no attempt to correct your markup and leaves you to hand-code every line of your posts. If you want total control over every line of your HTML then this is the option for you.

To disable wpautop entirely add these lines to your theme’s functions.php:

remove_filter('the_excerpt', 'wpautop');
remove_filter('the_content', 'wpautop');

However, wpautop is generally quite useful if most of your posts are simple text content and you only occasionally want to include HTML5 elements. Therefore, modifying wpautop to recognise HTML5 elements might be more practical.

Modify wpautop to recognise HTML5 elements

WordPress’ wpautop is part of the core functions and can be found in this file within your WordPress installation: wp-includes/formatting.php. It controls how and where paragraphs and line breaks are inserted in excerpts and post content.

In order to create a modified version of WordPress’ core wpautop function I started off by duplicating it in my theme’s functions.php file.

What I’ve experimented with is disabling wpautop and adding a modified copy of it – which includes HTML5 elements in its arrayss – to my theme’s functions.php file.

Add the following to your theme’s functions.php file and you’ll be able to use section, article, aside, header, footer, hgroup, figure, details, figcaption, and summary in your post content. (Probably best to try this in a testing environment first!)

/* -----------------------------
MODIFIED WPAUTOP - Allow HTML5 block elements in wordpress posts
----------------------------- */

function html5autop($pee, $br = 1) {
   if ( trim($pee) === '' )
      return '';
   $pee = $pee . "
"; // just to make things a little easier, pad the end
   $pee = preg_replace('|<br />s*<br />|', "

", $pee);
   // Space things out a little
    // *insertion* of section|article|aside|header|footer|hgroup|figure|details|figcaption|summary
   $allblocks = '(?:table|thead|tfoot|caption|col|colgroup|tbody|tr|td|th|div|dl|dd|dt|ul|ol|li|pre|select|form|map|area|blockquote|address|math|style|input|p|h[1-6]|hr|fieldset|legend|section|article|aside|header|footer|hgroup|figure|details|figcaption|summary)';
   $pee = preg_replace('!(<' . $allblocks . '[^>]*>)!', "
$1", $pee);
   $pee = preg_replace('!(</' . $allblocks . '>)!', "$1

", $pee);
   $pee = str_replace(array("
", "
"), "
", $pee); // cross-platform newlines
   if ( strpos($pee, '<object') !== false ) {
      $pee = preg_replace('|s*<param([^>]*)>s*|', "<param$1>", $pee); // no pee inside object/embed
      $pee = preg_replace('|s*</embed>s*|', '</embed>', $pee);
   }
   $pee = preg_replace("/

+/", "

", $pee); // take care of duplicates
// make paragraphs, including one at the end
   $pees = preg_split('/
s*
/', $pee, -1, PREG_SPLIT_NO_EMPTY);
   $pee = '';
   foreach ( $pees as $tinkle )
      $pee .= '<p>' . trim($tinkle, "
") . "</p>
";
   $pee = preg_replace('|<p>s*</p>|', '', $pee); // under certain strange conditions it could create a P of entirely whitespace
// *insertion* of section|article|aside
   $pee = preg_replace('!<p>([^<]+)</(div|address|form|section|article|aside)>!', "<p>$1</p></$2>", $pee);
   $pee = preg_replace('!<p>s*(</?' . $allblocks . '[^>]*>)s*</p>!', "$1", $pee); // don't pee all over a tag
   $pee = preg_replace("|<p>(<li.+?)</p>|", "$1", $pee); // problem with nested lists
   $pee = preg_replace('|<p><blockquote([^>]*)>|i', "<blockquote$1><p>", $pee);
   $pee = str_replace('</blockquote></p>', '</p></blockquote>', $pee);
   $pee = preg_replace('!<p>s*(</?' . $allblocks . '[^>]*>)!', "$1", $pee);
   $pee = preg_replace('!(</?' . $allblocks . '[^>]*>)s*</p>!', "$1", $pee);
   if ($br) {
      $pee = preg_replace_callback('/<(script|style).*?</\1>/s', create_function('$matches', 'return str_replace("
", "<WPPreserveNewline />", $matches[0]);'), $pee);
      $pee = preg_replace('|(?<!<br />)s*
|', "<br />
", $pee); // optionally make line breaks
      $pee = str_replace('<WPPreserveNewline />', "
", $pee);
   }
   $pee = preg_replace('!(</?' . $allblocks . '[^>]*>)s*<br />!', "$1", $pee);
// *insertion* of img|figcaption|summary
   $pee = preg_replace('!<br />(s*</?(?:p|li|div|dl|dd|dt|th|pre|td|ul|ol|img|figcaption|summary)[^>]*>)!', '$1', $pee);
   if (strpos($pee, '<pre') !== false)
      $pee = preg_replace_callback('!(<pre[^>]*>)(.*?)</pre>!is', 'clean_pre', $pee );
   $pee = preg_replace( "|
</p>$|", '</p>', $pee );

   return $pee;
}

// remove the original wpautop function
remove_filter('the_excerpt', 'wpautop');
remove_filter('the_content', 'wpautop');

// add our new html5autop function
add_filter('the_excerpt', 'html5autop');
add_filter('the_content', 'html5autop');

The results are not absolutely perfect but then neither is the original wpautop function. Certain ways of formatting the code will result in unwanted trailing </p> tags or a missing opening <p> tags.

For example, to insert a figure with caption into a post you should avoid adding the figcaption on a new line because an image or link appearing before the figcaption will end up with a trailing </p>.

<!-- this turns out ok -->
<figure>
  <a href="#"><img src="image.jpg" alt="" /></a><figcaption>A figure caption for your reading pleasure</figcaption>
</figure>

<!-- this turns out not so ok -->
<figure>
  <a href="#"><img src="image.jpg" alt="" /></a>
  <figcaption>A figure caption for your reading pleasure</figcaption>
</figure>

Another example would be when beginning the contents of an aside with a paragraph. You’ll have to leave a blank line between the opening aside tag and the first paragraph.

<aside>

This content could be a pullquote or information that is tangentially related to the surrounding content. But to get it wrapped in a paragraph you have to leave those blank lines either side of it before the tags.

</aside>

Room for improvement

Obviously there are still a few issues with this because if you format your post content in certain ways then you can end up with invalid HTML, even if it doesn’t actually affect the rendering of the page. But it seems to be pretty close!

Leave a comment or email me if you are using this function and find there that are instances where it breaks down. I ran numerous tests and formatting variations to try and iron out as many problems as possible but it’s unlikely that I tried or spotted everything.

Hopefully someone with more PHP and WordPress experience will be able to improve upon what I’ve been experimenting with, or find a simpler and more elegant solution that retains the useful wpautop functionality while allowing for the use of HTML5 elements in posts. Please share anything you find!

This is an experiment that creates social media icons using CSS and semantic HTML. It uses progressive enhancement to turn an unordered list of text links into a set of icons without the use of images or JavaScript.

Demo: Pure CSS social media icons

Support: Firefox 3.5+, Safari 4+, Chrome 4+, Opera 10+, IE8+.

CSS social media icons

The image below shows you the final appearance in modern browsers.

This experiment starts with a simple list of links, with each link using meaningful text, and then progressively styles each link to take on the appearance of the relevant social media icon. As a result, there should be support for screenreaders or users with CSS disabled.

I’ve also included basic text in the title attribute of each link to provide information for users who may not be familiar with what service a specific icon represents.

This is an experiment that uses CSS 2.1 and CSS3 that is not supported by Internet Explorer 6 and 7, therefore, you shouldn’t expect it to work in those browsers. CSS is not necessarily the most appropriate tool for this kind of thing either.

Example code

The technique I’ve used is much the same as the one used for the Pure CSS speech bubbles.

The HTML is just a basic unordered list of links to various social networking websites or services.

<ul>
   <li class="facebook"><a href="#non" title="Share on Facebook">Facebook</a></li>
   <li class="twitter"><a href="#non" title="Share on Twitter">Twitter</a></li>
   <li class="rss"><a href="#non" title="Subscribe to the RSS feed">RSS</a></li>
   <li class="flickr"><a href="#non" title="Share on Flickr">Flickr</a></li>
   <li class="delicious"><a href="#non" title="Bookmark on Delicious">Delicious</a></li>
   <li class="linkedin"><a href="#non" title="Share on LinkedIn">LinkedIn</a></li>
   <li class="google"><a href="#non" title="Bookmark with Google">Google</a></li>
   <li class="orkut"><a href="#non" title="Share on Orkut">Orkut</a></li>
   <li class="technorati"><a href="#non" title="Add to Technorati">Technorati</a></li>
   <li class="netvibes"><a href="#non" title="Add to NetVibes">NetVibes</a></li>
</ul>

I’ve applied some general styles to the elements that make up this list.

ul {
   list-style:none;
   padding:0;
   margin:0;
   overflow:hidden;
   font:0.875em/1 Arial, sans-serif;
}

ul li {
   float:left;
   width:66px;
   height:66px;
   margin:20px 20px 0 0;
}

ul li a {
   display:block;
   width:64px;
   height:64px;
   overflow:hidden;
   border:1px solid transparent;
   line-height:64px;
   text-decoration:none;
   /* css3 */
   text-shadow:0 -1px 0 rgba(0,0,0,0.5);
   -moz-border-radius:5px;
   -webkit-border-radius:5px;
   border-radius:5px; /* standards version last */
}

ul li a:hover,
ul li a:focus,
ul li a:active {
   opacity:0.8;
   border-color:#000;
}

Each icon uses it’s own set of styles. This is the CSS that created the RSS icon.

.rss a {
   position:relative;
   width:60px;
   padding:0 2px;
   border-color:#ea6635;
   text-transform:lowercase;
   text-indent:-186px;
   font-size:64px;
   font-weight:bold;
   color:#fff;
   background:#e36443;

   /* css3 */
   -moz-box-shadow:0 0 4px rgba(0,0,0,0.4);
   -webkit-box-shadow:0 0 4px rgba(0,0,0,0.4);
   box-shadow:0 0 4px rgba(0,0,0,0.4);
   background:-webkit-gradient(linear, left top, left bottom, from(#f19242), to(#e36443));
   background:-moz-linear-gradient(top, #f19242, #e36443);
   background:linear-gradient(top, #f19242, #e36443);
}

.rss a:before,
.rss a:after {
   content:"";
   position:absolute;
   bottom:10px;
   left:10px;
}

/* create circle */
.rss a:before {
   width:12px;
   height:12px;
   background:#fff;
   /* css3 */
   -moz-border-radius:12px;
   -webkit-border-radius:12px;
   border-radius:12px;
}

/* create the two arcs */
.rss a:after {
   width:22px;
   height:22px;
   border-style:double;
   border-width:24px 24px 0 0;
   border-color:#fff;
   /* css3 */
   -moz-border-radius:0 50px 0 0;
   -webkit-border-radius:0 50px 0 0;
   border-radius:0 50px 0 0;
}

Acknowledgements

This post was inspired by an experiment on insicdesigns that producing a few social media icons using CSS.

An experiment that uses pseudo-elements to create 84 simple GUI icons using CSS and semantic HTML. Shared as an exercise in creative problem solving and working within constraints. This is not a “production ready” CSS icon set.

Demo: Pure CSS GUI icons

Known support: Firefox 3.5+, Safari 5+, Chrome 5+, Opera 10.6+.

An exercise in constraint

Several months ago I was experimenting with the creation of common GUI icons with CSS. The HTML is very simple and it relies on CSS pseudo-elements rather than extraneous HTML elements. The technical aspects of this exercise might be of interest to others, so I’ve decided to share it.

Pseudo-elements provide many possibilities to developers interested in enhancing existing semantic HTML.

Example code

The technique behind this experiment is an expansion of the basic shape-creation that was used to make Pure CSS speech bubbles. Some of these GUI icons can only be created in browsers that support CSS3 transforms.

The HTML is a basic unordered list of links.

<ul>
  <li class="power"><a href="#non">Power</a></li>
  <li class="play"><a href="#non">Play</a></li>
  <li class="stop"><a href="#non">Stop</a></li>
  <li class="pause"><a href="#non">Pause</a></li>
</ul>

Each icon uses its own set of styles. For example, the key parts of the CSS responsible for the “expand” icon are as follows:

.expand a:before {
  content: "";
  position: absolute;
  top: 50%;
  left: 1px;
  width: 5px;
  height: 0;
  border-width: 7px 7px 0;
  border-style: solid;
  border-color: transparent #c55500;
  margin-top: -4px;
  /* css3 */
  -webkit-transform: rotate(-45deg);
  -moz-transform: rotate(-45deg);
  -o-transform: rotate(-45deg);
  transform: rotate(-45deg);
}

.expand a:after {
  content: "";
  position: absolute;
  top: 50%;
  left: 5px;
  width: 8px;
  height: 8px;
  border-width: 3px 0 0 3px;
  border-style: solid;
  border-color: #c55500;
  margin-top: -6px;
}

.expand a:hover:before,
.expand a:focus:before,
.expand a:active:before {
  border-color: transparent #730800;
}

.expand a:hover:after,
.expand a:focus:after,
.expand a:active:after {
  border-color: #730800;
}

The demo page contains a full set of user interaction and media player control icons, as well as other common icons. For now, several icons actually require more than one element as CSS 2.1 only specifies 2 pseudo-elements per element that can contain generated content. The CSS3 Generated and Replaced Content Module allows for an unlimited number of pseudo-elements but has yet to be fully implemented in any modern browser.

Research into improving the cross-browser consistency of both the “clearfix” and “overflow:hidden” methods of containing floats. The aim is to work around several bugs in IE6 and IE7.

This article introduces a new hack (with caveats) that can benefit the “clearfix” methods and the new block formatting context (NBFC) methods (e.g. using overflow:hidden) of containing floats. It’s one outcome of a collaboration between Nicolas Gallagher (that’s me) and Jonathan Neal.

If you are not familiar with the history and underlying principles behind methods of containing floats, I recommend that you have a read of Easy clearing (2004), Everything you know about clearfix is wrong (2010), and Clearfix reloaded and overflow:hidden demystified (2010).

Consistent float containment methods

The code is show below and documented in this GitHub gist. Found an improvement or flaw? Please fork the gist or leave a comment.

Micro clearfix hack: Firefox 3.5+, Safari 4+, Chrome, Opera 9+, IE 6+

.cf {
  /* for IE 6/7 */
  *zoom: expression(this.runtimeStyle.zoom="1", this.appendChild(document.createElement("br")).style.cssText="clear:both;font:0/0 serif");
  /* non-JS fallback */
  *zoom: 1;
}

.cf:before,
.cf:after {
  content: "";
  display: table;
}

.cf:after {
  clear: both;
}

Overflow hack (NBFC): Firefox 2+, Safari 2+, Chrome, Opera 9+, IE 6+

.nbfc {
  overflow: hidden;
  /* for IE 6/7 */
  *zoom: expression(this.runtimeStyle.zoom="1", this.appendChild(document.createElement("br")).style.cssText="clear:both;font:0/0 serif");
  /* non-JS fallback */
  *zoom: 1;
}

The GitHub gist also contains another variant of the clearfix method for modern browsers (based on Thierry Koblentz’s work). It provides greater visual consistency (avoiding edge-case bugs) for even older versions of Firefox.

The only difference from existing float-containment methods is the inclusion of a CSS expression that inserts a clearing line-break in IE 6 and IE 7. Jonathan and I found that it helps to resolve some of the visual rendering differences that exist between these browsers and more modern ones. First I’ll explain what some of those differences are and when they occur.

Containing floats in IE 6/7

In IE 6 and IE 7, the most common and robust method of containing floats within an element is to give it “layout” (find out more: On having Layout). Triggering “layout” on an element in IE 6/7 creates a new block formatting context (NBFC). However, certain IE bugs mean that previous float containment methods don’t result in cross-browser consistency. Specifically, this is what to expect in IE 6/7 when creating a NBFC:

1. The top- and bottom-margins of non-floated child elements are contained within the ancestor element that has been given “layout”. (Also expected in other browsers when creating a NBFC)
2. The bottom-margins of any right-floated descendants are contained within the ancestor. (Also expected in other browsers when creating a NBFC)
3. The bottom-margins of any left-floated children are not contained within the ancestor. The margin has no effect on the height of the ancestor and is truncated, having no affect outside of the ancestor either. (IE 6/7 bug)
4. In IE 6, if the right edge of the margin-box of a left-floated child is within 2px of the left edge of the content-box of its NBFC ancestor, the float’s bottom margin reappears and is contained within the parent. (IE 6 bug)
5. Unwanted white-space can appear at the bottom of a float-container. (IE 6/7 bug)

There is a lack of consistency between IE 6/7 and other browsers, and between IE 6 and IE 7. Thanks to Matthew Lein for his comment that directed me to this IE 6/7 behaviour. It was also recently mentioned by “Suzy” in a comment on Perishable Press.

IE 6/7’s truncation of the bottom-margin of left-floats is not exposed in many of the test-cases used to demonstrate CSS float containment techniques. Using an IE-only CSS expression helps to correct this bug.

The CSS expression

Including the much maligned <br style="clear:both"> at the bottom of the float-container, as well as creating a NBFC, resolved all these inconsistencies in IE 6/7. Doing so prevents those browsers from collapsing (or truncating) top- and bottom-margins of descendant elements.

Jonathan suggested inserting the clearing line-break in IE 6/7 only, using CSS expressions applied to fictional CSS properties. The CSS expression is the result of many iterations, tests, and suggestions. It runs only once, the first time an element receives the associated classname.

*zoom: expression(this.runtimeStyle.zoom="1", this.appendChild(document.createElement("br")).style.cssText="clear:both;font:0/0 serif");

It is applied to zoom, which is already being used to help contain floats in IE 6/7, and the use of the runtimeStyle object ensures that the expression is replaced once it has been run. The addition of font:0/0 serif prevents the occasional appearance of white-space at the bottom of a float-container. And the * hack ensures that only IE 6 and IE 7 parse the rule.

It’s worth noting that IE 6 and IE 7 parse almost any string used as CSS property. An earlier iteration used the entirely fictitious properties “-ms-inject” or “-ie-x” property to exploit this IE behaviour.

*-ie-x: expression(this.x||(this.innerHTML+='<br style="clear:both;font:0/0">',this.x=1));

However, this expression is evaluated over and over again. Using runtimeStyle instead avoids this. Sergey Chikuyonok also pointed out that using innerHTML destroys existing HTML elements that may event handlers attached to them. By using document.createElement and appendChild you can insert the new element without removing all the events attached to other descendant elements.

Containing floats in more modern browsers

There are two popular methods to contain floats in modern browsers. Creating a new block formatting context (as is done in IE 6/7 when hasLayout is triggered) or using a variant of the “clearfix” hack.

Creating a NBFC results in an element containing any floated children, and will prevent top- and bottom-margin collapse of non-floated children. When combined with the enhanced IE 6/7 containment method, it results in consistent cross-browser float containment.

The other method, known as “clearfix”, traditionally used a single :after pseudo-element to clear floats in a similar fashion to a structural, clearing HTML line-break. However, to prevent the top-margins of non-floats from collapsing into the margins of their float-containing ancestor, you also need to use the :before pseudo-element. This is the approach taken in Thierry Koblentz’s “clearfix reloaded”. In contemporary browsers, the micro clearfix hack is also suitable.

The method presented in this article should help improve the results of cross-browser float containment, whether you predominantly use “clearfix” or the NBFC method. The specific limitations of both the “clearfix” and various NBFC methods (as outlined in Thierry’s articles) remain.

Problems

Using a CSS expression to change the DOM in IE 6/7 creates problems of its own. Obviously, the DOM in IE 6/7 is now different to the DOM in other browsers. This affects any JavaScript DOM manipulation that may depend on :last-child or appending new children.

This is still an experimental work-in-progress that is primarily research-driven rather than seeking to become a practical snippet of production code. Any feedback, further testing, and further experimentation from others would be much appreciated.

Thanks to these people for contributing improvements: Jonathan Neal, Mathias Bynens, Sergey Chikuyonok, and Thierry Koblentz.

Applying conditional classnames to the html element is a popular way to help target specific versions of IE with CSS fixes. It was first described by Paul Irish and is a feature of the HTML5 Boilerplate. Despite all its benefits, there are still a couple of niggling issues. Here are some hacky variants that side-step those issues.

An article by Paul Irish, Conditional stylesheets vs CSS hacks? Answer: Neither!, first proposed that conditional comments be used on the opening html tag to help target legacy versions of IE with CSS fixes. Since its inclusion in the HTML5 Boilerplate project, contributors have further refined the technique.

However, there are still some niggling issues with the “classic” conditional comments approach, which Mathias Bynens summarized in a recent article on safe CSS hacks.

1. The Compatibility View icon is displayed in IE8 and IE9 if you are not setting the X-UA-Compatible header in a server config.
2. The character encoding declaration might not be fully contained within the first 1024 bytes of the HTML document if you need to include several attributes on each version of the opening html tag (e.g. Facebook xmlns junk).

You can read more about the related discussions in issue #286 and issue #378 at the HTML5 Boilerplate GitHub repository.

The “bubble up” conditional comments method

Although not necessarily recommended, it looks like both of these issues can be avoided with a bit of trickery. You can create an uncommented opening html tag upon which any shared attributes (so no class attribute) can be set. The conditional classes are then assigned in a second html tag that appears after the <meta http-equiv="X-UA-Compatible"> tag in the document. The classes will “bubble up” to the uncommented tag.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta http-equiv="X-UA-Compatible"
          content="IE=edge,chrome=1">
    <meta charset="utf-8">
    <!--[if lt IE 7]><html class="no-js ie6"><![endif]-->
    <!--[if IE 7]><html class="no-js ie7"><![endif]-->
    <!--[if IE 8]><html class="no-js ie8"><![endif]-->
    <!--[if gt IE 8]><!--><html class="no-js"><!--<![endif]-->

    <title>Document</title>
  </head>
  <body>
  </body>
</html>

Fork the Gist

The result is that IE8 and IE9 won’t ignore the <meta http-equiv="X-UA-Compatible"> tag, the Compatibility View icon will not be displayed, and the amount of repeated code is reduced. Obviously, including a second html tag in the head isn’t pretty or valid HTML.

If you’re using a server-side config to set the X-UA-Compatible header (instead of the meta tag), then you can still benefit from the DRYer nature of using two opening html tags and it isn’t necessary to include the conditional comments in the head of the document. However, you might still want to do so if you risk not containing the character encoding declaration within the first 1024 bytes of the document.

<!DOCTYPE html>
<html lang="en">
<!--[if lt IE 7]><html class="no-js ie6"><![endif]-->
<!--[if IE 7]><html class="no-js ie7"><![endif]-->
<!--[if IE 8]><html class="no-js ie8"><![endif]-->
<!--[if gt IE 8]><!--><html class="no-js"><!--<![endif]-->
  <head>
    <meta charset="utf-8">
    <title>Document</title>
  </head>
  <body>
  </body>
</html>

Fork the Gist

The “preemptive” conditional comments method

Another method to prevent the Compatibility View icon from showing was found by Julien Wajsberg. It relies on including a conditional comment before the DOCTYPE. Doing this seems to help IE recognise the <meta http-equiv="X-UA-Compatible"> tag. This method isn’t as DRY and doesn’t have the character encoding declaration as high up in the document, but it also doesn’t use 2 opening html elements.

<!--[if IE]><![endif]-->
<!DOCTYPE html>
<!--[if lt IE 7]><html class="no-js ie6"><![endif]-->
<!--[if IE 7]><html class="no-js ie7"><![endif]-->
<!--[if IE 8]><html class="no-js ie8"><![endif]-->
<!--[if gt IE 8]><!--><html class="no-js"><!--<![endif]-->
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <meta charset="utf-8">
    <title>Document</title>
  </head>
  <body>
  </body>
</html>

Fork the Gist

While it’s interesting to explore these possibilities, the “classic” method is still generally the most understandable. It doesn’t create invalid HTML, doesn’t risk throwing IE into quirks mode, and you won’t have a problem with the Compatibility View icon if you use a server-side config.

If you find any other approaches, or problems with those posted here, please leave a comment but also consider adding what you’ve found to the relevant issues in the HTML5 Boilerplate GitHub repository.

Thanks to Paul Irish for feedback and suggestions.

Using SVG is currently the best way to create icon libraries for apps. Icons built with SVG are scalable and adjustable, but also discrete, which allows them to be incrementally loaded and updated. In contrast, icons built as fonts cannot be incrementally loaded or updated. This alone makes SVG icons the better choice for high-performance apps that rely on code-splitting and incremental deploys.

This post describes how to make a package of React components from a library of SVG icons. Although I’m focusing on React, making any other type of package is also possible. At Twitter I used the approach described here to publish the company’s SVG icon library in several different formats: optimized SVGs, plain JavaScript modules, React DOM components, and React Native components.

Using the icons

The end result is a JavaScript package that can be installed and used like any other JavaScript package.

yarnpkg add @acme/react-icons

Each icon is available as an individually exported React component.

import IconCamera from '@acme/react-icons/camera';

This allows your module bundler to package only the icons that are needed, and icons can be efficiently split across chunks when using code-splitting. This is a significant advantage over icon libraries that require fonts and bundle all icons into a single component.

// entire icon library is bundled with your app
import Icon from '@acme/react-icons';
const IconCamera = <Icon name='camera' />;

Each icon is straightforward to customize (e.g., color and dimensions) on a per-use basis.

import IconCamera from '@twitter/react-icons/camera';
const Icon = (
  <IconCamera
    style={{ color: 'white', height: '2em' }}
  />
);

Although the icons render to SVG, this is an implementation detail that isn’t exposed to users of the components.

Creating components

Each React component renders an inline SVG, using path and dimensions data extracted from the SVG source files. A helper function called createIconComponent means that only a few lines of boilerplate are needed to create a component from SVG data.

import createIconComponent from './utils/createIconComponent';
import React from 'react';
const IconCamera = createIconComponent({
  content: <g><path d='...'></g>,
  height: 24,
  width: 24
});
IconCamera.displayName = 'IconCamera';
export default IconCamera;

This is an example of what the createIconComponent function looks like when building components for a web app like Twitter Lite, which is built with React Native for Web.

// createIconComponent.js
import { createElement, StyleSheet } from 'react-native-web';
import React from 'react';

const createIconComponent = ({ content, height, width }) =>
  (initialProps) => {
    const props = {
      ...initialProps,
      style: StyleSheet.compose(styles.root, initialProps.style),
      viewBox: `0 0 ${width} ${height}`
    };

    return createElement('svg', props, content);
  };

const styles = StyleSheet.create({
  root: {
    display: 'inline-block',
    fill: 'currentcolor',
    height: '1.25em',
    maxWidth: '100%',
    position: 'relative',
    userSelect: 'none',
    textAlignVertical: 'text-bottom'
  }
});

Setting the fill style to currentcolor allows you to control the color of the SVG using the color style property instead.

All that’s left is to use scripts to process the SVGs and generate each React component.

Creating icon packages

A complete example of one way to do this can be found in the icon-builder-example repository on GitHub.

The project structure of the example tool looks like this.

.
├── README.md
├── package.json
├── scripts/
    ├── build.js
    ├── createReactPackage.js
    └── svgOptimize.js
└── src/
    ├── alerts.svg
    ├── camera.svg
    ├── circle.svg
    └── ...

The build script uses SVGO to optimize the SVGs, extract SVG path data, and extract metadata. The example packager for React then uses templates to create a package.json and the React icon components shown earlier.

import createIconComponent from './utils/createIconComponent';
import React from 'react';
const ${componentName} = createIconComponent({
  height: ${height},
  width: ${width},
  content: <g>${paths}</g>
});
${componentName}.displayName = '${componentName}';
export default ${componentName};

Additional packagers can be included to build other package types from the same SVG source. When the underlying icon library changes, it only takes a couple of commands to rebuild hundreds of icons and publish new versions of each package.

The Home Ministry had on Thursday allowed chariot construction with a condition that no religious congregation should take place around the Ratha Khala.

The industrial hub faces a massive shortfall in revenues amid growing cost of combating the pandemic

The NCMC chaired by Cabinet Secretary Rajiv Gauba met on Friday to review the situation arising out of the gas leak

Plenert, Gerhard Johannes, author

Greene, Jeffrey R., author

Allen, David T

Meyler, Kerrie, author

Lara, Arturo, author

Kiran, D. R., author

Dobson, Michael Singer, author

Egerton, Peter, author

Munson, Chuck, author

Wellhoff, Thierry, author

Clark, Robert A., author

Scholz, Miklas, author

Bosworth, Michael T

Zacker, Craig

Wildermuth, Daniel

Bishop, Russell, 1950-

Bush, Mirabai, 1939- author

Bush, Mirabai, 1939- author

Interview with Mehraneh D. Jafari, MD, and Kasra Ziai, MD, authors of Association of Compensation From the Surgical and Medical Device Industry to Physicians and Self-declared Conflict of Interest

Interview with Ananias C Diokno, MD, author of Effect of Group-Administered Behavioral Treatment on Urinary Incontinence in Older Women: A Randomized Clinical Trial

Interview with Roxana Cobo, MD, author of Superiorly Pediculated Superficial Musculoaponeurotic System Ligament Flap to Control the Supratip

Interview with Julia Baudry, PhD, author of Association of Frequency of Organic Food Consumption With Cancer Risk: Findings From the NutriNet-Santé Prospective Cohort Study, and Jorge E. Chavarro, MD, ScD, author of Organic Foods for Cancer Prevention—Worth the Investment?

Interview with Ivo Abraham, PhD, author of Economic Evaluation of Talimogene Laherparepvec Plus Ipilimumab Combination Therapy vs Ipilimumab Monotherapy in Patients With Advanced Unresectable Melanoma

Interview with Andreas M. Zeiher, MD, author of Association of Mutations Contributing to Clonal Hematopoiesis With Prognosis in Chronic Ischemic Heart Failure, and Peter Libby, MD, author of CHIPping Away at the Pathogenesis of Heart Failure

Interview with Joseph M. Unger, PhD, author of Association of Patient Comorbid Conditions With Cancer Clinical Trial Participation

Interview with Sam P. Most, MD, author of Assessment of Persistent and Prolonged Postoperative Opioid Use Among Patients Undergoing Plastic and Reconstructive Surgery

Interview with George F. Sawaya, MD, author of Estimated Quality of Life and Economic Outcomes Associated With 12 Cervical Cancer Screening Strategies: A Cost-effectiveness Analysis, and Sarah Feldman, M.D. M.P.H., author of Screening Options for Preventing Cervical Cancer

Interview with Donald A. Redelmeier, MD, FRCPC, MSHSR, FACP, author of Association Between Statin Use and Risk of Dementia After a Concussion

Interview with Ian A. Maher, author of Association of Smoking and Other Factors With the Outcome of Mohs Reconstruction Using Flaps or Grafts