How to Avoid Theme & Plugin Shortcode Conflicts in WordPress

We all have experienced this: you buy a premium theme that is really great, and you also buy an amazing plugin (one of mine for example!) but putting the theme and the plugin together just doesn’t work at all. So what? Is the plugin or the theme having bugs?

Most part of the time, when this happens it’s when you are using shortcodes. Let’s imagine you just bought a plugin to handle “testimonials”. You read carefully the documentation and you know that to display the testimonials you need to include the following shortcode [testimonials]. But when you do so, nothing appears.

The reason why the shortcode isn’t replaced by testimonials, is because your theme AND the plugin define the same exact shortcode.

As plugins files are loaded before themes files they are overwritten and not fully taken into account in this case.

That’s why i wanted to show you a simple method to deregister the theme shortcode and replace it by the plugin’s one.

Step 1: Create A Simple Plugin

We need to create a simple plugin:

<?php
/*
Plugin Name: Avoid Shortcodes conflicts
Plugin URL: http://remicorson.com
Description: A little plugin to avoid conflicts bewteen shortcodes
Version: 1.0
Author: Remi Corson
Author URI: http://remicorson.com
Contributors: corsonr
Text Domain: rc_asc
Domain Path: languages
*/

Step 2: Check If The Shortcode Exists

This is the most important step. It’s where you check for the existence of a shortcode. WordPress has a “$shortcode_tags” global variable that store the list of all registered shortcodes. So, we just need to go through this variable and check if the shortcode we are looking for makes part of it.

/**
 * Check if a shortcode is already registered
 *
 * @since 1.0
 *
 * @param $shortcode string The shortcode slug to test
 *
 * @return void
 */
function rc_asc_shortcode_exists( $shortcode = false ) {
	
	global $shortcode_tags;

	//echo '<pre>'; var_dump($shortcode_tags); echo '</pre>';
 
	if ( ! $shortcode )
		return false;
 
	if ( array_key_exists( $shortcode, $shortcode_tags ) )
		return true;
 
	return false;

}

This is the generic function that we will use in a more specific function including the shortcode slug to look for. This function returns TRUE if the shortcode exists, or FALSE if it doesn’t.

Step 3: Remove The Shortcode & Register The New One

The next function is using the rc_asc_shortcode_exists() we just created. It simply check for the existence of the shortcode, replaces it if it exists, or add the shortcode if it’s not already registered.

/**
 * Check if a shortcode is already registered and replace it
 *
 * @since 1.0
 *
 * @return void
 */
function rc_asc_replace_shortcode() {

	$shortcode = 'testimonials';
	
	if( rc_asc_shortcode_exists( $shortcode ) ) {
		remove_shortcode( $shortcode );
		add_shortcode( $shortcode, 'my_testimonials_function' );
	} else {
		add_shortcode( $shortcode, 'my_testimonials_function' );
	}
}

Step 4: Define The New Shortcode Function

All you have to do is to define the content of the “my_testimonials_shortcode()” function, and you’re done!

/**
 * Creates the new shortcode
 *
 * @since 1.0
 *
 * @return void
 */
function my_testimonials_function() {

	return 'this replaces the previous shortcode!';
}

As you can see the previously declared shortcode is now replaced by the right shortcode.

Post Author: Remi

Remi is an expert WordPress developer that coded many great free and premium themes and plugins. His experience on WordPress allows him to produce great stuff and to propose advanced tutorials. (remicorson.com)

Disclosure: This page contains external affiliate links that may result in us receiving a comission if you choose to purchase said product. The opinions on this page are our own. We do not receive payment for positive reviews.
Got something to say? Join the discussion.
  1. Rudd says:
    Never had this problem before since I don't use shortcode much. However, this will become handy whenever I had clients with the same problem.
  2. Sami Keijonen says:
    Theme authors should not use content shortcodes in their themes. Not the public ones anyway.
    • AJ Clarke | WPExplorer says:
      AJ Clarke | WPExplorer
      I agree. That's why I made a plugin for shortcodes used in my themes ;)
      Admin
  3. Craig says:
    Interesting article worth reading... I would suggest in your proposed code that if a shortcode is already registered, you should throw an error instead of silently replacing the currently registered shortcode with something else. Although your code will now work, you've now broken some one else's code. I'm also curious why you only create shortcodes in plugins and not themes. It doesn't look like you've really improved this situation in any way by doing so. There's still the possibility that multiple plugins will try to register the same shortcode. Thank you for discovering this potential problem and discussing how to better handle it. Cheers, Craig
    • AJ Clarke | WPExplorer says:
      AJ Clarke | WPExplorer
      Hi Craig, This solution isn't good for everyone, but for example if you are a developer working with a client that doesn't want to change themes but wants you to maybe modify a current shortcode without editing the theme, then you can replace it via a plugin. Make sense?
      Admin
  4. EByrd says:
    Instead of replacing one with the other would it be possible to rename one of the shortcodes? I have this exact problem... it's even with Testimonials. The theme testimonials shortcode does one thing, the plug in shortcode does something completely different... I really need BOTH. In my case I would want to give the theme shortcode hihger priority... but that would completely remove the plugin shortcode function. Which I'd rather keep. Suggestions?
    • AJ Clarke says:
      AJ Clarke
      Hey, The issue is if you've already used the shortcode on your site, because if you were to lets say do a search/replace of your database for the shortcode to rename it, it's going to rename all of them. If the issue isn't that you've used the shortcodes, but rather that you want to use the plugin shortcode and not the theme shortcode, I think you'll need to manually strip the one out of your theme (or rename it), unless they've provided a method for you to remove the shortcode via hooks. You should contact the theme developer and ask what would be the best thing to do. I understand the frustration! To avoid these situations I always prefix my shortcodes, such as my free shortcodes plugin all the shortcodes start why symple_. I think all developers really need to.
      Admin
  5. OLIK ABDUL says:
    Hi, Please help me, i use shortcode from plugin and i want overwrite the shortcode in my theme not use plugin. Thanks
  6. luroch says:
    Hi Man. Thanks for the lesson! What if I want to prevent a shortcode from running (ideally removing it) based on a specific attribute? For example, I have 3 toggles on a post: [toggle title="yes"] [toggle title="maybe"] [toggle title="no"], and I need to prevent [toggle title="no"] from showing. More than that, I need to completely remove togles with "no" as a title attribute, but without affecting the other toggles. Would you help me achieving that?
    • AJ Clarke says:
      AJ Clarke
      I don't quite understand the point of this, why would you specifically add a shortcode to a page if you don't want it to run? Why not just not add it in the first place?
      Admin
  7. luroch says:
    The shortcode is already added and I have more than 1 thousand posts with it. That's the reason. But do not bother. I already came up with the solution. If anybody wants to know, just use if ( $atts ['title'] == "no" ) { return " "; } else { code for the shortcode }
    • AJ Clarke says:
      AJ Clarke
      Hi Luroch, Gotcha! Another good thing you could do though is to just search the database for the shortcode and strip it out completely ;)
      Admin

Leave a Reply