Create, register and use shortcodes in WordPress

WordPress shortcodes are a feature allowing you to easily add dynamic content to your posts and pages. Shortcodes are placeholders for dynamic content and are replaced with processed content when your page is rendered. Let’s look at how to create, register and use shortcodes in WordPress.

Many plugins will utilise placeholders so that you can place and configure the plugin content. In this tutorial we are going to have a look at how you can make your own.

What are you trying to display?

Before creating your shortcode it is important to decide on what content you want to display. This could be anything from a simple text snippet to a complex gallery of images.

Knowing what content you want to display will allow you to think about how you would like to structure your shortcode.

For this tutorial we will use a shortcode to display a simple greeting to the user. We will pass a name using an attribute and use it to display a prepared message.

How to create a WordPress shortcode function

To start with we need to put our function somewhere. If you are making a plugin then feel free to use my plugin skeleton, otherwise open your functions.php from either your plugin or theme template.

With most things in WordPress, to create a shortcode we need to write a custom function and then register it. Our function can take any parameters we may want to pass it, and will then return the content that we want to display.

function gavs_shortcode_tutorial($atts) {
    $atts = shortcode_atts(array(
        'name' => 'phil',
    ), $atts);
    
    return 'Hello ' . $atts['name'] . '! Welcome to my website.';
}

Our function asks for an array of shortcode attributes as arguments. We then use shortcode_atts() to set all the default values for the attributes that haven’t been provided (basically merging the two arrays). Finally, we are returning a string of what we want displayed on the front end.

How to register your WordPress shortcode

Now that we’ve created a shortcode function, we need to register it with WordPress using the add_shortcode() function. You can register your shortcode function like this:

add_shortcode('shortcode_tutorial', 'gavs_shortcode_tutorial');

We’ve now registered our shortcode with WordPress, and told it to use the gavs_shortcode_tutorial() function to generate our content when the shortcode is called.

This is how it might look if you’ve been using my plugin skeleton:

<?php
/*
Plugin Name: Gav’s WordPress shortcode tutorial
Plugin URI: https://www.gavsblog.com
Description: A plugin demonstrating a basic use of WordPress shortcodes
Version: 1.0
Author: Gav de Ste Croix
Author URI: https://www.gavsblog.com
*/

class gb_shortcode_tutorial_plugin {

    public function __construct() {
        // Hook the scripts
        add_action('wp_enqueue_scripts', array($this, 'enqueue_scripts'));
        
        // Register the shortcode
        add_shortcode('shortcode_tutorial', 'gavs_shortcode_tutorial');
    }

    /**
    * Function to add plugin scripts
    * @return void
    */
    public function enqueue_scripts() {
        // Styles
        wp_enqueue_style('gb_object_oriented_skeleton', plugins_url('assets/css/style.css', __FILE__), null, '');

        // Scripts
        wp_enqueue_script('gb_object_oriented_skeleton', plugins_url('assets/js/script.js', __FILE__), array('jquery'), '', true);
    }

    /**
    * Function to add a simple shortcode returning a greeting
    * @param $atts
    * @return string
    */
    public function gavs_shortcode_tutorial($atts) {
        $atts = shortcode_atts(array(
            'name' => 'World',
        ), $atts);
        
        return 'Hello ' . $atts['name'] . '! Welcome to my website.';
    }
}

// Instantiate
new gb_shortcode_tutorial_plugin();

Note: This is a tutorial; when you use shortcodes in practice you should always use a prefix to avoid conflicts with other plugins and themes. Make sure you document your shortcodes well so that you and other developers can easily refer and reference them.

Call the shortcode in your content

Now that we’ve registered a shortcode, it is really easy to use. We can simply use the following tag in our WordPress content editor for posts and pages, and WordPress will pass it through the do_shortcode() function for us. The do_shortcode() function searches for shortcodes and runs them.

[shortcode_tutorial name="Gav"] // output = Hello Gav! Welcome to my website.

If we want to use a shortcode in our theme templates (i.e. not in the WordPress content editor) then we can pass it through the do_shortcode function ourselves.

<?php do_shortcode('[shortcode_tutorial name="Gav"]') ?>

Note: It is important to understand that by passing ‘name=”Gav”‘ we are actually overriding the default attributes. If we call the function without the attributes then the shortcode function will render using the defaults.

[shortcode_tutorial] // output = Hello Phil! Welcome to my website.

That’s it! With just a few simple steps, we can create WordPress shortcodes and add dynamic content to our posts and pages. Hopefully this tutorial has given you a good starting point to try something more ambitious.