Using WordPress ‘add_shortcode()’ PHP function

by

The add_shortcode() function in WordPress PHP allows you to add a new shortcode. It’s important to ensure that the shortcode tag being added is unique to prevent conflicts with other already-added shortcode tags. If there are duplicate tags, the tag loaded last will take precedence.

Usage

Here’s a simple example of how to use the add_shortcode() function:

add_shortcode( 'mytag', 'mytag_callback_function' );

function mytag_callback_function( $atts ){
    return "This is my custom shortcode.";
}

In this example, a new shortcode [mytag] is created. When this shortcode is used in a post or page, it will output the text “This is my custom shortcode.”

Parameters

  • $tag (string, required): The shortcode tag to be searched in post content.
  • $callback (callable, required): The callback function to run when the shortcode is found. This function is passed three parameters by default: an array of attributes ($atts), the shortcode content or null if not set ($content), and the shortcode tag itself ($shortcode_tag).

More information

See WordPress Developer Resources: add_shortcode()
This function is part of the WordPress core and is not deprecated as of the last update in 2021. For related functions and more detailed information, refer to the WordPress Developer Resources link provided.

Examples

Basic Shortcode

This example demonstrates a basic shortcode that returns a simple string.

add_shortcode( 'simpletag', 'simpletag_callback' );
function simpletag_callback( $atts ) {
    return "This is a simple shortcode.";
}

In this case, [simpletag] will output “This is a simple shortcode.”

Shortcode with Attributes

This shortcode uses attributes to customize the output.

add_shortcode( 'greetingtag', 'greetingtag_callback' );
function greetingtag_callback( $atts ) {
    $atts = shortcode_atts( array(
        'name' => 'World'
    ), $atts, 'greetingtag' );

    return "Hello, " . $atts['name'] . "!";
}

The shortcode [greetingtag name="John"] will output “Hello, John!”

Shortcode with Enclosed Content

This example demonstrates a shortcode that wraps around content.

add_shortcode( 'boldtag', 'boldtag_callback' );
function boldtag_callback( $atts, $content = null ) {
    return "<strong>" . $content . "</strong>";
}

When you use [boldtag]your text[/boldtag], it will output your text in bold.

Shortcode in a Class

If your plugin is designed as a class, you can define your shortcode like this:

add_shortcode( 'classtag', array( 'MyPlugin', 'classtag_callback' ) );

class MyPlugin {
    public static function classtag_callback( $atts, $content = null ) {
        return "This is a class-based shortcode.";
    }
}

This will let you use the [classtag] shortcode.

Shortcode that Includes a Template

This example includes a template part within the shortcode.

function templatetag_callback( $atts ) {
    $attributes = shortcode_atts( array(
        'title' => false,
        'limit' => 4,
    ), $atts );

    ob_start();
    get_template_part( 'template-parts/templatetag', null, $attributes );
    return ob_get_clean();
}
add_shortcode( 'templatetag', 'templatetag_callback' );

In this case, the shortcode [templatetag title="My Title" limit="2"] will include the template part ‘template-parts/templatetag’ with the provided attributes.

Remember, when you create your shortcodes, it’s good practice to hook them to the init hook. This ensures that WordPress has time to initialize properly. For example:

add_action( 'init', 'register_my_shortcodes' );
function register_my_shortcodes(){
    add_shortcode( 'mytag', 'mytag_callback_function' );
}

And finally, be aware that shortcode attribute names are always converted to lowercase before they are passed into the handler function. So, if you pass attributes like [myshortcode FooBar="one" SomethingElse="two"], you would access them in your callback function as $atts['foobar'] and $atts['somethingelse'].