Custom Shortcode

Shortcodes are a powerful feature in WordPress that allow you to create custom code snippets that can be used in posts, pages, and widgets to display dynamic content or execute custom functionality. To add a WordPress shortcode, we have to use the add_shortcode() function:

add_shortcode( $tag, $callback )

• $tag string (Required) The “tag” of the shortcode to define
• $callback callable (Required) The callback function to run when the shortcode is used

Here’s an example of how to create a simple shortcode in WordPress:

// Add the shortcode [my_shortcode]
add_shortcode( 'my_shortcode', function() {
    return 'Hello world!';
});

The above PHP code snippet creates a shortcode called [my_shortcode] that outputs Hello world! when it is used. It is generally a good practice to pass the name of a callback function as the second parameter, instead of declaring an anonymous function. See the example below:

// Add the shortcode [my_shortcode] that calls the my_shortcode_callback() function when used
add_shortcode( 'my_shortcode', 'my_shortcode_callback' );

/**
 * The callback function for the [my_shortcode] shortcode
 */
function my_shortcode_callback() {
	return 'Hello world!';
}

How to add shortcodes that accept attributes

In order to pass parameters to the callback function of your shortcode, you need enable your shortcode to accept attributes. The simplest version of a shortcode that accepts attributes is as follows:

// Add the shortcode [my_shortcode] that calls the my_shortcode_callback() function when used
add_shortcode( 'my_shortcode', 'my_shortcode_callback' );

/**
 * The callback function for the [my_shortcode] shortcode
 * 
 * @param array $attributes An associative array of attributes and their values
 */
function my_shortcode_callback( $attributes ) {

   return $attributes['id'];
  
}

Now the shortcode will output the value of the id attribute:

[my_shortcode id='123'] // Outputs: 123

It’s a good practice to set default values for the attributes, for which you can use the shortcode_atts() function:

// Add the shortcode [my_shortcode] that calls the my_shortcode_callback() function when used
add_shortcode( 'my_shortcode', 'my_shortcode_callback' );

/**
 * The callback function for the [my_shortcode] shortcode
 * 
 * @param array $attributes An associative array of attributes and their values
 */
function my_shortcode_callback( $attributes ) {

  // Parse the attributes and set defaults, see shortcode_atts()
  $parsed_attributes = shortcode_atts( array(
		'id' => 'default_id',
		'slug' => 'default_slug,
	), $attributes );

	return 'ID is ' . $parsed_attributes['id'] . ' and slug is ' . $parsed_attributes['slug'];
}

Now, when you use the shortcode [my_shortcode] without providing any attributes, the shortcode will assume their default values. If you do provide a value for the attributes, then the values you pass will be used instead of the default values:

[my_shortcode] // Outputs: 'ID is default_id and slug is default_slug'
[my_shortcode id='123'] // Outputs: 'ID is 123 and slug is default_slug'
[my_shortcode slug='hello-world'] // Outputs: 'ID is default_id and slug is hello-world'
[my_shortcode id='123' slug='hello-world'] // Outputs: 'ID is 123 and slug is hello-world'

Remember to use return and not echo – anything that is echoed will be output to the browser, but it won’t appear in the correct place on the page.

WordPress Developer Handbook

If the shortcode produces a lot of HTML then you can use ob_start() to start capturing the HTML output and then return it to as string as follows:

function my_shortcode_callback() {

	ob_start();

	?><p>Lots of HTML content goes here ...</p><?php

	return ob_get_clean();
}

How to add shortcodes that enclose content

The enclosed content of a shortcode, is always passed as the second parameter to the callback function. Since users might not always add content (or might not use the shortcode as an enclosing shortcode) it is a good practice to provide a default value for the second parameter to the callback function, like so:

function my_shortcode_handler( $atts, $content = null )

Here’s a simple example of a shortcode that allows enclosed content:

// Add the shortcode [wrapper] with the callback function wrapper_shortcode()
add_shortcode( 'wrapper', 'wrapper_shortcode' );

// Declare the callback function 
function wrapper_shortcode( $atts, $content = null ) {

  // Return the HTML that includes the $content
	return '<div class="wrapper">' . $content . '</div>';
}

Now you can enclose content within the shortcode, like so:

[wrapper]Content here[/wrapper]

And the shortcode renders the following HTML:

<div class="wrapper">Content here</div>

Programmatically render shortcodes

If you need to render the output of a shortcode in a template file for example, you can use do_shortcode(). For example:

do_shortcode( '[my_shortcode]' );

For more information, check out the Shortcode API!