add_shortcode( string $tag, callable $callback )

User Contributed Notes

1. Skip to note 10 content

   Codex 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 15You must log in to vote on the helpfulness of this note

   Examples

   Simplest example of a shortcode tag using the API: [footag foo="bar"]

   add_shortcode( 'footag', 'wpdocs_footag_func' );
   function wpdocs_footag_func( $atts ) {
   	return "foo = {$atts['foo']}";
   }

   Example with nice attribute defaults: [bartag foo="bar"]

   add_shortcode( 'bartag', 'wpdocs_bartag_func' );
   function wpdocs_bartag_func( $atts ) {
   	$atts = shortcode_atts( array(
   		'foo' => 'no foo',
   		'baz' => 'default baz'
   	), $atts, 'bartag' );
   
   	return "foo = {$atts['foo']}";
   }

   Example with enclosed content: [baztag]content[/baztag]

   add_shortcode( 'baztag', 'wpdocs_baztag_func' );
   function wpdocs_baztag_func( $atts, $content = "" ) {
   	return "content = $content";
   }

   If your plugin is designed as a class write as follows:

   add_shortcode( 'baztag', array( 'MyPlugin', 'wpdocs_baztag_func' ) );
   class MyPlugin {
   	public static function wpdocs_baztag_func( $atts, $content = "" ) {
   		return "content = $content";
   	}
   }
2. Skip to note 11 content

   Denis Žoljom 5 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 12You must log in to vote on the helpfulness of this note

   When adding `add_shortcode() ` function in a plugin, it’s good to add it in a function that is hooked to `init` hook. So that WordPress has time to initialize properly.

   add_action( 'init', 'wpdocs_add_custom_shortcode' );
   
   function wpdocs_add_custom_shortcode() {
   	add_shortcode( 'footag', 'wpdocs_footag_func' );
   }

   As described in the plugins handbook.

   • There is currently (2020-12-23) no such recommendation in the plugins handbook nor in the codex.

     Bart Kuijper 4 years ago
3. Skip to note 12 content

   Ahmad Karim 4 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

   Example of add_shortcode function that uses get_template_part function to include a template.

   function wpdocs_the_shortcode_func( $atts ) {
   	$attributes = shortcode_atts( array(
   		'title' => false,
   		'limit' => 4,
   	), $atts );
   	
   	ob_start();
   
   	// include template with the arguments (The $args parameter was added in v5.5.0)
   	get_template_part( 'template-parts/wpdocs-the-shortcode-template', null, $attributes );
   
   	return ob_get_clean();
   
   }
   add_shortcode( 'wpdocs_the_shortcode', 'wpdocs_the_shortcode_func' );
4. Skip to note 13 content

   nasifshuvo123 3 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

   For wppb plugin boilerplate I add code to define_public_hooks()
   $this->loader->add_action( 'init', $plugin_public, 'register_shortcodes' );

   Then in public folder, in class_public file I added:

   public function register_shortcodes(){
   
   		add_shortcode( 'sample-shortcode','shortcode_function'  );
   		function shortcode_function(  ) {
   			return "Hello Shortcode";
   		}
   	}
5. Skip to note 14 content

   Matthias Kittsteiner 3 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

   Beware that the first argument passed to the callback is an empty string if no attributes are set in the shortcode. So a type declaration will fail:

   “Fatal error: Uncaught Error: Argument 1 passed to shortcode_callback() must be of the type array, string given”

   Use a check whether $arguments is not an array and if so, replace it with an empty array:

   function shortcode_callback( $attributes, string $content, string $shortcode ) {
   	if ( ! is_array( $attributes ) ) {
   		$attributes = [];
   	}
   	
   	// do stuff
   }

   • If using shortcode_atts() this will already be taken care of. If using PHP 8.0+, you can also declare the parameter as array|string. function shortcode_callback( array|string $atts, string $content, string $shortcode_tag ) { $atts = shortcode_atts( array( 'attribute' => 'default_value' ), $atts ); // do stuff }

     Old account 9 months ago
   • If using shortcode_atts() this will already be taken care of. If using PHP 8.0+, you can also declare the parameter as array|string.

     Gerard Reches 9 months ago
6. Skip to note 15 content

   Patrick Johanneson 7 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

   Notes (from the Codex — https://codex.wordpress.org/Function_Reference/add_shortcode#Notes)

   • The shortcode callback will be passed three arguments: the shortcode attributes, the shortcode content (if any), and the name of the shortcode.
   • There can only be one hook for each shortcode. Which means that if another plugin has a similar shortcode, it will override yours or yours will override theirs depending on which order the plugins are included and/or ran.
   • Shortcode attribute names are always converted to lowercase before they are passed into the handler function. Values are untouched.
   • Note that the function called by the shortcode should never produce output of any kind. Shortcode functions should return the text that is to be used to replace the shortcode. Producing the output directly will lead to unexpected results. This is similar to the way filter functions should behave, in that they should not produce expected side effects from the call, since you cannot control when and where they are called from.
7. Skip to note 16 content

   Xedin Unknown 1 year ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

   ⚠️⚠️
   Currently, and for some time now, viewing a post with a shortcode in the editor caused the shortcode to get rendered. This is very unexpected behaviour described in an old issue. It can, for example, cause the post to become uneditable via the admin if there’s an error in the shortcode, such as some visitor-facing area variables or functions not being declared, etc.

   To go around this, as mentioned in a comment, use the is_admin() function to prevent computation on admin pages.

   • The only time I ran in to an issue with saving is when I used echo instead of return in the callback. Maybe this was fixed in the past few months… or you were using echo like me. Also, if you use echo the shortcode content will not appear where the shortcode was placed. So it is best to return the output of the callback function.

     Jason Raveling 11 months ago
8. Skip to note 17 content

   Sabbir Mia 3 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

   $atts: an associative array of attributes, you can access the associative array anywhere.
   $content: the enclosed content (if the shortcode is used in its enclosing form)

   /**
    * Appends a <a> tag with URL to the content.
    * 
    * @param array $atts the shortcode attributes.
    * @param sring $content the editor enclosed content.
    * @return string
    */
   function button_callback( $atts, $content ) {
   	// It's a default value.
   	$default = array(
   		'url' => '',
   	);
   	// You will pass default value after that user define values.
   	$button_attrs = shortcode_atts( $default, $atts );
   
   	return sprintf( '<a href="%s">%s</a>', $button_attrs['url'], do_shortcode( $content ) );
   }
   
   add_shortcode( 'test-button', 'button_callback' );
9. Skip to note 18 content

   SpeakOut! 2 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

   When passing values via the shortcode e.g. [myshortcode FooBar="one" SomethingElse="two"] the keys in the array are transformed to lowercase

   The array passed to the callback function will be: Array( foobar => "one", somethingelse=> "two" )

   Don’t be like me and spend hours trying to figure out why the values weren’t being passed.