How to Use WordPress do_shortcode: Tutorial & Best Practices

Wish you could use WordPress shortcodes in theme template files or execute them via PHP? Make it a reality with the do_shortcode function. Shortcodes continue to play a vital role in the WordPress ecosystem despite the shift toward the block editor (AKA Gutenberg). Using brackets and text, such as [yourshortcode], you can efficiently embed content and perform various tasks.

This all sounds great, but you can't simply place the code in your template theme, as it won't work. You'll need to add some extra code to make it work, and there are several things to consider. Keep reading to learn how it works and some other important best practices for using WordPress shortcodes in your template files.

• How does WordPress do_shortcode work?

• WordPress do_shortcode Example
• Troubleshooting When WordPress do_shortcode Is Not Working
• Are there any risks with using WordPress do_shortcode?
• Getting Started With WordPress do_shortcode

How does WordPress do_shortcode work?

With the do_shortcode function, you can essentially wrap your shortcode in the do_shortcode PHP function and use that to add the shortcode directly to your site's template files.

You can put the shortcode anywhere on your site, including the following locations:

• Header
• Footer
• Single templates (e.g. a single blog post)
• Archive templates (e.g. the page that lists all of your blog posts)

To use it, all you need to do is add the shortcode inside the WordPress do_shortcode function like this:

<?php echo do_shortcode( '[your_actual_shortcode]'); ?>

You can then add this function directly to your template files. Or, you can use WordPress hooks to insert it at specific locations.

Not sure how it works? Let's look at an example.

WordPress do_shortcode Example

To help you understand how the do_shortcode function works, let's look at a real example.

Let's say you created a form with the WPForms plugin and now you want to embed that form directly in your theme's template files using do_shortcode.

Here's how to do it.

1. Backup your site and choose a child theme.

Because you'll be editing your template files directly in this example, it's essential to do two things before you start:

1. Back up your WordPress site just in case anything goes wrong.
2. Make sure to use a child theme. If you don't, your template changes will get overwritten the next time you update your theme. Read our full guide to WordPress child themes if you're not sure what to do here.

Once you've done that, you're ready to begin.

2. Prepare your shortcode.

To get started, you'll want to prepare the shortcode that you're going to use.

For our WPForms example, you can find the shortcode in the WPForms interface.

2. Edit the template file.

Next, you need to edit the template file where you want to include your shortcode. For this example, let's say that you want to add the form below every single blog post and page.

To accomplish that, you would need to find your theme's single.php template. To add the shortcode below the content, you would want to add the do_shortcode function below the the_content function in the template file.

You can make your edits via WordPress' built-in theme editor by going to Appearance → Theme Editor. Or, you can connect via an FTP client and edit the files that way.

3. Add the WordPress do_shortcode function.

To finish things out, just add the do_shortcode function with the shortcode inside at the proper location. Make sure to echo the do_shortcode function — otherwise, you won't see the output on the frontend.

Once you save your changes, you should see your shortcode's output at the location where you added the function. Here's what it looks like with our example and the default Twenty Twenty-One theme.

If everything is working fine, you're done. If you're having issues with WordPress do_shortcode not working, continue on to the next section for some troubleshooting steps.

Troubleshooting When WordPress do_shortcode Is Not Working

If you're having issues with WordPress do_shortcode not working, here are some basic troubleshooting steps to consider.

1. Echo the shortcode.

By itself, WordPress do_shortcode just returns a value. If you want to actually display the output of the shortcode, you need to echo the do_shortcode function.

If you notice in the WordPress do_shortcode example above, we make sure to always echo the do_shortcode function to display the value.

2. Double-check that you're using quotation marks properly.

If you experience a PHP error after adding a shortcode with do_shortcode, it might be an issue with the quotation marks that you're using.

Some shortcodes let you add parameters inside the shortcode, which can cause problems if you make a mistake with the quotation marks that you use.

For example, let's say you want to add a shortcode like this:

[contact-form-7 id="44" title="Main Contact Form"]

The shortcode already includes double quotation marks. So, if you try to use double quotation marks for the do_shortcode function, you'll likely trigger an error.

The solution? Just use single quotes for the PHP function.

Here's the wrong way to do it — notice how the shortcode is wrapped in double quotes outside:

echo do_shortcode("[contact-form-7 id="44" title="Main Contact Form"]");

Here's the correct way to do it — notice how the shortcode is now wrapped in single quotes, while there are still double quotes inside the shortcode:

echo do_shortcode('[contact-form-7 id="44" title="Main Contact Form"]');

3. Confirm that you are using the correct shortcode.

This might seem obvious, but it can actually be a little tricky. Some plugins will use the exact same shortcode syntax but implement things slightly differently so that it's not really a WordPress shortcode.

To you, it looks exactly like a shortcode, so you think that it should work fine in WordPress do_shortcode. But to your WordPress site, it's not actually a shortcode, which is why do_shortcode isn't working..

Are there any risks with using WordPress do_shortcode?

The WordPress do_shortcode function can be really handy when you only have a shortcode and you need some way to add it to a template or PHP code.

With that being said, you should generally try to avoid using it when possible.

Why should you avoid it?

The issue is mainly performance-related. While using do_shortcode won't automatically slow down your site, it's not the most optimal technique. It forces your site to run through all existing shortcodes just to execute the one you need. This includes default WordPress shortcodes, theme shortcodes, and plugin shortcodes. It's recommended to explore alternative approaches. Let's discuss a few options.

WordPress do_shortcode Alternatives

1. Use the PHP Function if provided

Nowadays, many plugins give you both a shortcode and a PHP function as embed options. When you have both of these options, you should always choose to use the PHP function instead of the WordPress do_shortcode function. There's really no added complexity and it will improve the performance and efficiency of your site.

2. Find the shortcode’s callback function.

If the plugin doesn't offer a PHP function and you want to avoid using do_shortcode for performance reasons, there are still other options available. However, these solutions can be complex. If you prefer simplicity, it's best to stick with do_shortcode.

Instead of using the shortcode and do_shortcode, you can locate the shortcode's callback function. This function is the actual PHP function that is executed when the shortcode is used. You can then echo this function instead of using do_shortcode.

However, there are two downsides to this:

1. It can be tricky to find the callback function if you're not a very technical person.
2. It can be really tricky if the callback is inside an object class. You might not be able to access the callback directly, which necessitates creating a custom callback utility and is beyond the scope of this article.

For a lot of simpler plugins, you can find the callback function without too much difficulty. For this example, let's say you want to use the shortcode from the Current Year and Copyright Shortcode plugin.

Here's the simplest way to do this:

1. Download the plugin and extract the zip file so you can easily access all of the plugin's files.
2. Use software that will let you run a search on all of the files in that folder. Notepad ++ is a solid free option that makes it easy to do this.
3. Search for the shortcode that you were planning to use in the WordPress do_shortcode function.

You should see something like this:

add_shortcode( 'cy', 'jr_cy_cy' );

In this example:

• [cy] is the shortcode
• jr_cy_cy() is the actual function that the shortcode invokes

With do_shortcode, you would implement it like this:

echo do_shortcode( '[cy]' );

But now that you have the callback function, you can use the function directly like this:

echo jr_cy_cy();

You get the exact same effect, but you've reduced the work that your site has to do.

Getting Started With WordPress do_shortcode

WordPress do_shortcode simplifies the process of using shortcodes in template files. Just place the shortcode within the do_shortcode function and echo it in the desired template location. Pay attention to the quotation marks used, as the difference between single and double quotes is important.

Though do_shortcode is simple to use, it's best to avoid it whenever feasible, as calling a PHP function directly is more performance-friendly. If a plugin offers both a shortcode and a PHP function, prioritize using the PHP function. Even without a PHP function, you may find and use the associated callback function directly.

If do_shortcode is the only method that works, stick with it. Try it out to enhance flexibility when working with template files.