add_shortcode( string $tag, callable $callback )

Adds a new shortcode.

Contents

Description Description

Care should be taken through prefixing or other means to ensure that the shortcode tag being added is unique and will not conflict with other, already-added shortcode tags. In the event of a duplicated tag, the tag loaded last will take precedence.

Top ↑

Parameters Parameters

$tag

(string) (Required) Shortcode tag to be searched in post content.

$callback

(callable) (Required) The callback function to run when the shortcode is found. Every shortcode callback is passed three parameters by default, including an array of attributes ($atts), the shortcode content or null if not set ($content), and finally the shortcode tag itself ($shortcode_tag), in that order.

Top ↑

More Information More Information

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. This 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 an 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 unexpected side effects from the call since you cannot control when and where they are called from.

Top ↑

Source Source

File: wp-includes/shortcodes.php 

function add_shortcode( $tag, $callback ) {
	global $shortcode_tags;

	if ( '' === trim( $tag ) ) {
		_doing_it_wrong(
			__FUNCTION__,
			__( 'Invalid shortcode name: Empty name given.' ),
			'4.4.0'
		);
		return;
	}

	if ( 0 !== preg_match( '@[<>&/\[\]\x00-\x20=]@', $tag ) ) {
		_doing_it_wrong(
			__FUNCTION__,
			sprintf(
				/* translators: 1: Shortcode name, 2: Space-separated list of reserved characters. */
				__( 'Invalid shortcode name: %1$s. Do not use spaces or reserved characters: %2$s' ),
				$tag,
				'& / < > [ ] ='
			),
			'4.4.0'
		);
		return;
	}

	$shortcode_tags[ $tag ] = $callback;
}

Expand full source code Collapse full source code View on Trac

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/functions.php: _doing_it_wrong()

Mark something as being incorrectly called.

Top ↑

Changelog Changelog

Changelog
Version Description
2.5.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
    Contributed by dingo-d —

    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.

  3. Skip to note 3 content
    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
    Contributed by Patrick Johanneson —

    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.
  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Ahmad Karim —

    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' );

    Expand full source codeCollapse full source code

You must log in before being able to contribute a note or feedback.