How to Add New Shortcode to WordPress! [+2 Examples]

add_shortcode Function Introduction

WordPress introduced the add_shortcode function to let developers register custom shortcodes when developing new features.

When adding a new shortcode, you must specify a tag which is the name of your shortcode, and a callback function to give WordPress your desired content.

Your callback function receives three parameters. First, an array of attributes; second, the user content; and finally, the tag you set when registering this shortcode. (order: 1- attributes, 2- content, 3- tag)

Example of adding a new shortcode that prints “Hello World!” text:

//callback for the shortcode
function hello_world_shortcode_callback( $attributes, $content, $tag ){
	return 'Hello World!';
}

//register the hello world shortcode
function hello_world_shortcode(){
	add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
}

add_action( 'init', 'hello_world_shortcode' );

Now you can use this shortcode by typing [hello-world] inside the WordPress post editor to try it.

Notice the return in the above code? You must return the value you want to print. So do not echo the value.

If you use echo instead of return, the “Hello World!” text will be printed before the surrounding content.

Note: as a developer mentioned on WordPress.org, you better add your custom shortcodes in a function that is hooked to the WP init hook. This helps WP to have time to initiate your new shortcodes properly.

add_shortcode Function Syntax

add_shortcode( string $tag,  callable $callback )

add_shortcode Function Parameters

• $tag: Name tag for this shortcode. If duplicated, the lastly defined will override others (you can use a prefix to prevent this).
• $callback: Name of the function that returns the value you want to print.

How to Use Shortcodes in the WordPress Post Editor?

To use a shortcode in the WordPress editor (Gutenberg or Classic editor), you must use it inside a bracket.

In our example of adding a ‘hello world!’ text using a custom shortcode, we defined the hello-world shortcode. To use it, we must type [hello-world] in the post editor.

Another option is to write shortcode in complete form, like this:

[hello-world][/hello-world]

How to Use a WordPress Shortcodes in PHP?

You can call shortcodes in PHP codes with the do_shortcode() function of WordPress. Here is an example of the do_shortcode() function using our hello-world shortcode:

do_shortcode( '[hello-world]' )

How to Pass Data from Shortcode to Callback Function?

Option 1: pass data between start and close tag of the shortcode

You can pass a text to the callback function in between of shortcode start and close tag. For example:

[hello-world]from me to[/hello-world]

To use this data, we can do something like this:

//callback for the shortcode
function hello_world_shortcode_callback( $attributes, $content, $tag ){
	return 'Hello '. $content .' World!';
}

//register the hello world shortcode
function hello_world_shortcode(){
	add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
}

add_action( 'init', 'hello_world_shortcode' );

Now if you type [hello-world]from me to[/hello-world] in WordPress editor, it will print “Hello from me to World!“.

Option 2: pass data as an attribute

Another option is to set attributes in the shortcode and get them in the callback function, for example:

[hello-world from="me" to="world"][/hello-world]

To get the from and to in the callback function, we can use the first parameter in our callback function:

//callback for the shortcode
function hello_world_shortcode_callback( $attributes, $content, $tag ){
	return 'Hello from '. $attributes['from'] . ' to ' . $attributes['to'] . '!';
}

//register the hello world shortcode
function hello_world_shortcode(){
	add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
}

add_action( 'init', 'hello_world_shortcode' );

Now if you type test [hello-world from="me" to="the world"][/hello-world] inside the WordPress editor, it will print “Hello from me to the world!” for you.

Examples of Adding Custom Shortcodes to WordPress

Here I provided two examples of adding a new shortcode to WordPress. You can use them in the WP post editor to print useful texts when you write a post.

1- New Shortcode for printing the current year

To print current year that will change over time, we will define the current-year shortcode in WordPress, using this code:

//callback for current year the shortcode
function current_year_shortcode_callback( $attributes, $content, $tag ){
	return date('Y');
}

//register the current year shortcode
function current_year_shortcode(){
	add_shortcode( 'current-year', 'current_year_shortcode_callback' );
}

add_action( 'init', 'current_year_shortcode' );

Now you can type [current-year] in WordPress editor to print the current year between your content.

2- New Shortcode for printing list of users

To print list of registered users in WordPress, we will define the users-list shortcode, using this code:

// function that runs when shortcode is called
function my_custom_users_list() {
	$args = array(); //define arguments if you need
	$users = get_users($args);

	$listHtml = '<ul>';
	foreach($users as $user){
		$listHtml .= '<li>' . $user->data->display_name . '</li>';
	}
	$listHtml .= '</ul>';
	return $listHtml;
}

//register my-users-list shortcode
function register_my_users_list_shortcode(){
	add_shortcode('users-list', 'my_custom_users_list');
}
add_action( 'init', 'register_my_users_list_shortcode' );

After defining this in the functions.php file of the active theme, or maybe your custom WordPress plugin, you can open the WordPress post editor to type [users-list] and print all registered users’ names with bullet points.