Aqua SVG Sprite Plugin

Penned on the 29th of September in the year 2017. It was a Friday.

SVG image sprites allow you to add sharp, fast-loading images to your sites with all the flexibility you'd expect from the SVG format, but they can be time consuming or complicated to generate. No more! Enter the Aqua SVG Sprite WordPress plugin.

Check out the Aqua SVG Sprite plugin, available on the official WordPress plugin repository!

Jump To…

Why use this plugin?

SVG, or Scalable Vector Graphics, allow you to add resolution-independent images to your websites. These images are generally much sharper and smaller in file size compared to other formats like JPEG.

However, each SVG image needs to be requested separately, which slows down your website. Adding SVG images to a sprite allows the browser to download multiple images with just one request, then show the individual pieces of the sprite separately. Depending on the number of images you’re displaying, this can significantly speed up your website.

Creating a Sprite

Aqua SVG Sprite adds a new SVG Sprite menu to the WordPress sidebar, which functions a lot like the default Posts or Pages menus; you can add, edit, and delete individual SVG images under All Items.

When you add or edit an item, You’re able to choose a few things:

  1. The Title makes it easy to find an individual SVG and is also used for selecting an SVG by the shortcode generator button.
  2. The Slug is used as the ID for the symbol in the sprite, which essentially allows WordPress to extract one SVG image from the sprite and display it on the page.
  3. The Aqua SVG Sprite Image is where you add a single SVG image that gets added to the sprite.
  4. There are some basic instructions on usage, pre-populated with the ID and group (explained in the next section) for the individual SVG you’re viewing.
  5. In the sidebar, you can select a Sprite Group as explained in the next section.
  6. Last of course, Publish adds the SVG to the sprite.

Creating Additional Sprites

If you’d like to use more than one sprite (the built in General sprite), you can add additional groups by going to the sidebar and clicking SVG Sprite > Sprite Groups. These work similar to WordPress tags, except you can only add each individual SVG image to one sprite group. Since they’re compiled into separate sprite groups, marking the same SVG for multiple groups would duplicate code, somewhat defeating the purpose of a sprite.

After you add a new Sprite Group, it appears as a selection in the right sidebar’s Sprite Group selector when creating or editing individual SVG images.

Shortcode Usage

Aqua SVG Sprite will add a convenient [SVG] button to your editor (anywhere a WYSIWYG with TinyMCE appears). Clicking this brings up a menu in which you can select an image and add some optional attributes.

  1. You can chose the sprite group and individual SVG image you wish to add to the page.
  2. You can optionally add a Width and Height to the SVG. If not controlling this through CSS instead, typically you can add a digit and it will use that as a pixel value; for example, if you enter 25 for both the output will be 25x25px in size (assuming no CSS overrides either value).
  3. You can add additional advanced options as a pseudo array that gets separated into individual property/value pairs. For instance, you could add viewbox=0 0 1000 1000,fill=aquamarine to change the viewBox and fill color of the SVG image output.

Shortcode Examples

You could for example display the image titled “Some Slug” from the default sprite group titled “General” like so (notice however it needs the slug and not the title since slugs are always unique):

[aqua-svg slug="some-slug"]

If “Some Slug” were part of the “Some Group” sprite, you would use:

[aqua-svg slug="some-slug" sprite="some-group"]

If you wanted a fill color and to define the viewBox, you would add a pseudo-array of HTML properties for more control:

[aqua-svg slug="some-slug" sprite="some-sprite" attr="viewbox=0 0 1000 1000,fill=aquamarine"]

PHP Usage

Developers can also use the underlying API directly, avoiding the abstracted shortcode option. A call to the_aqua_svg( 'some-slug' ); will echo the SVG <use> code for the sprite with an ID, or post slug, of “some-slug”. If you tag an image with a different sprite group than the default “general” one, you access those by calling the_aqua_svg( 'some-slug', 'some-group' );.

PHP Examples

Full PHP usage options are as follows:

<?php get_aqua_svg( string $slug, string $sprite = 'general', array $attr( 'attribute' => 'value' ) ) ?>

For example:

    // grab the "twitter-icon" SVG from the "social-icons" group with a couple properties
    $attr = array(
        'viewbox'   => '0 0 1000 1000',
        'fill'      => 'aquamarine'
    $svg_string = get_aqua_svg( 'twitter-icon', 'social-icons', $attr );
    // echo it manually
    echo $svg_string;

    // essentially outputs the following (simplified a bit for brevity):
    // <svg viewbox="0 0 1000 1000" fill="aquamarine">
    //    <use xlink:href=""></use>
    // </svg>

Use With Other Plugins

Since Aqua SVG Sprite treats images as a custom post type, it integrates well with plugins like the amazing Advanced Custom Fields. In particular, you can allow your users to select SVG icons from your sprite using the Relationship field, and since Aqua SVG Sprite’s images are set as the featured image, you can even check Featured Image under “Elements: Selected elements will be displayed in each result” to show previews of each individual SVG image from the sprite. Further, you can restrict selections to a particular sprite group since they’re treated as tags.

in category development