The Complete Guide to Creating Custom Shortcodes in WordPress

WordPress shortcodes are used to 1) reduce the amount of code you need to write; 2) simplify the usage of WordPress plugins, themes, and other functions. They behave like macros, when you insert a shortcode, it is replaced with a snippet of code. It could be anything.

WordPress comes with some pre-defined shortcodes, like [gallery] and [caption], and they’re also included with many popular plugins and themes. You can also create your own custom shortcodes to do things like create columns on your WordPress website.

In this post, we’ll take you step-by-step through the process of creating and using your own custom shortcodes. We’ll walk you through the entire process of creating a new shortcode and show you how to modify and control the shortcode attributes and functions.

Please note that this is a more advanced post that will go into details on how to create shortcodes. If working with code is beyond your technical expertise, and you just want the easiest way to get started with creating and using shortcodes you may want to start with a shortcode plugin.

When creating your own shortcodes, there are two things you need to do:

  1. Create the shortcode handler function. A shortcode function is a function that takes optional parameters (attributes) and returns a result.
  2. Register the shortcode handler function. Use the built-in WordPress add_shortcut function to register custom shortcodes.

Preparing WordPress for Custom Shortcodes

Although it’s not required, it’s a good idea to keep your custom shortcodes in their own file. Alternatively, you may add them to your theme’s functions.php file.

First, create a new file named custom-shortcodes.php, and save it inside the same folder as your theme’s functions.php file.

Then, inside the newly created file, add the following block of code:


Next, open the functions.php file, and add the following line of code:


You’re now ready to start adding your custom shortcodes.

Basic Shortcodes

In this first example, we’re going to create a basic WordPress shortcode that inserts the Day Of The Indie avatar image below.

Creating the Shortcode

The first step is to create the shortcode function. Inside the custom-shortcodes.php file, add the following block of code:

function dotiavatar_function() {
     return '<img src="" 
    alt="doti-avatar" width="96" height="96" class="left-align" />';

In the code example above, the dotiavatar_function function returns a pre-determined image named avatar-simple.png.

The next step is to register the shortcode with WordPress using the built-in function add_shortcode. Still inside custom-shortcodes.php, add the following line of code:

add_shortcode('dotiavatar', 'dotiavatar_function');

When you register a shortcode using the add_shortcode function, you pass in the shortcode tag ($tag) and the corresponding function ($func)/hook that will execute whenever the shortcut is used.

In this case, the shortcut tag is dotiavatar and the hook is dotiavatar_function.

Note: When naming tags, use lowercase letters only, and do not use hyphens; underscores are acceptable.

Using the Shortcode

Now that you have the shortcode created and registered, it’s time to try it out! Whenever you want the DOTI avatar to appear inside the post content, you can use the shortcode instead:


Shortcodes with Parameters (Attributes)

In the previous example, there wasn’t much room to change things up. Let’s say, instead of pushing a single image, we’d like to be able to set which image to use using a parameter. You can do that by adding some attributes ($atts).

Once again, inside custom-shortcodes.php, add another function, like so:

function dotirating_function( $atts = array() ) {
    // set up default parameters
     'rating' => '5'
    ), $atts));
    return "<img src="$rating-star.png" 
    alt="doti-rating" width="130" height="188" class="left-align" />";

The function above accepts a single parameter: rating. If a rating value is not passed, it uses a default string value of 5. It does this by unwrapping the array of attributes using the built-in shortcode_atts function, and combining the default values with values that may have been passed into the function.

Don’t forget to register the shortcode:

add_shortcode('dotirating', 'dotirating_function');

With the shortcode function created, and the hook added, the shortcode is now ready to be used inside your post content:

[dotirating rating=3]

Alternatively, you can omit the rating, and just go with the default value:


And that’s it! You now know how to create self-closing WordPress shortcodes. But there is another kind you can create.

Enclosing Shortcodes

Up until now, we’ve been working with self-closing shortcodes. But there is another type of shortcode: enclosing shortcodes.

Enclosing shortcodes allow you to use a BBCode-style format. That is, a style that looks like this:


Enclosing shortcodes are useful for when you need to manipulate the enclosed content. For example, let’s say you have a particular style of button you use your website; you could use the HTML code to generate that button/style every time you need to use it, or you can set up a custom enclosing shortcode instead.

By using an enclosing shortcode, you’re able to keep the focus on the content, rather than on the code.

Creating the Shortcode

Again, inside the custom-shortcodes.php file, add the following block of code:

function dotifollow_function( $atts, $content = null ) {
    return '<a href="" target="blank" class="doti-follow">' . $content . '</a>';

In the code block above, the $content = null is used to identify this function as an enclosing shortcode. And, inside that function, you’re wrapping your content ($content) within the HTML code.

OK, now it’s time to register the shortcode:

add_shortcode('dotifollow', 'dotifollow_function');

And that’s it! Your shortcode is ready to be used.

Using the Shortcode

Using an enclosing shortcode isn’t much different than using a self-closing one. Like HTML, you just need to make sure you have an opening and a closing statement:

[dotifollow]Follow us on Twitter![/dotifollow]

Of course, this is just a basic example. You can also add parameters to an enclosing shortcode, like you do with a self-closing shortcode.

Inside custom-shortcodes.php, add one more function:

function dotibutton_function( $atts = array(), $content = null ) {
    // set up default parameters
     'link' => '#'
    ), $atts));
    return '<a href="'. $link .'" target="blank" class="doti-button">' . $content . '</a>';

And then register the shortcode:

add_shortcode('dotibutton', 'dotibutton_function');

This new function let’s you set a link for the button using the following syntax:

[dotibutton link="/bits-bytes/"]Shop Now![/dotibutton]

With enclosing shortcodes, you can do a lot with very little code.

A Word About Widgets

By default, shortcodes are only supported in posts, pages, or custom post types; they are not supported in sidebar widgets. To add support for widgets, you need to add the following code to the functions.php file:

add_filter( 'widget_text', 'shortcode_unautop' );
add_filter( 'widget_text', 'do_shortcode' );

Once you do that, you can use shortcodes in widgets- just like you do in posts/pages.

Wrapping Things Up

Adding your own shortcodes doesn’t take a lot of effort- especially once you understand how they’re implemented. If you want to learn more, check out the WordPress codex.






New Posts in your inbox

  1. What about saving the data? either for re-use or copying the shortcode, changing attributes and saving as new shortcode?

    Is that possible… I mean to have it with an editor window, where one can save copies of the shortcodes to past into other pages or edit later?

    I have a basic setup with 9 attributes, but it get tedious having to retype all them over, and over again, with incremental changes each time

  2. This does not work at all. I followed the directions to the letter, and instead of the shortcode calling the PHP function, it just appears in my pages for my users to see, like “[shortcode]”. Great.

  3. Hi Tammy

    This post is awesome. I have been searching for literally days for a simple explanation and this post is just perfect. I do have a question however (!). Hope that’s ok! Could you add to the above to explain how to load libraries your php code relies on. I have built some awesome php code that runs beautifully on my local web server but it does require some external third party libraries. After reading your post I know I will easily manage to get the code onto my wordpress site but it obviously won’t work unless I also load up the libraries it uses. How do I get those loaded? Where do I put them? And do I just uses regular “require” statement in my functions code? How does it all work?

  4. Hi,
    Great tut.
    I am learning WP. I have a custom template page, That has google map and html table under google map. I would like to use this template in many pages on my site. Can I call my custom template page a short code and inject this short code in different places?

  5. Thank you very much, I actually added this module on my site, and glad it worked, otherwise I’ve to remove the [separate] from all (150) pages of my website.
    Thanks again Tammy~