Title: add_shortcode
Published: April 25, 2014
Last modified: April 28, 2025
---
# add_shortcode( string $tag, callable $callback )
## In this article
* [Description](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#description)
* [Parameters](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#parameters)
* [More Information](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#more-information)
* [Source](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#source)
* [Related](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#related)
* [Changelog](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#changelog)
* [User Contributed Notes](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#user-contributed-notes)
[ Back to top](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#wp--skip-link--target)
Adds a new shortcode.
## [Description](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#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.
## [Parameters](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#parameters)
`$tag`stringrequired
Shortcode tag to be searched in post content.
`$callback`callablerequired
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.
## [More Information](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#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.
## [Source](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#source)
```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;
}
```
[View all references](https://developer.wordpress.org/reference/files/wp-includes/shortcodes.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/shortcodes.php#L63)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/shortcodes.php#L63-L90)
## [Related](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#related)
| Uses | Description |
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |
Retrieves the translation of $text.
|
| [_doing_it_wrong()](https://developer.wordpress.org/reference/functions/_doing_it_wrong/)`wp-includes/functions.php` |
Marks something as being incorrectly called.
|
| Used by | Description |
| [WP_Embed::__construct()](https://developer.wordpress.org/reference/classes/wp_embed/__construct/)`wp-includes/class-wp-embed.php` |
Constructor
|
| [WP_Embed::run_shortcode()](https://developer.wordpress.org/reference/classes/wp_embed/run_shortcode/)`wp-includes/class-wp-embed.php` |
Processes the shortcode.
|
## [Changelog](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#changelog)
| Version | Description |
| [2.5.0](https://developer.wordpress.org/reference/since/2.5.0/) | Introduced. |
## [User Contributed Notes](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#user-contributed-notes)
1. [Skip to note 10 content](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#comment-content-444)
2. [Codex](https://profiles.wordpress.org/codex/) [ 11 years ago ](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-444)
3. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-444)
Vote results for this note: 17[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-444)
4. **Examples**
5. Simplest example of a shortcode tag using the API: `[footag foo="bar"]`
6. ```php
add_shortcode( 'footag', 'wpdocs_footag_func' );
function wpdocs_footag_func( $atts ) {
return "foo = {$atts['foo']}";
}
```
7. Example with nice attribute defaults: `[bartag foo="bar"]`
8. ```php
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']}";
}
```
9. Example with enclosed content: `[baztag]content[/baztag]`
10. ```php
add_shortcode( 'baztag', 'wpdocs_baztag_func' );
function wpdocs_baztag_func( $atts, $content = "" ) {
return "content = $content";
}
```
11. If your plugin is designed as a class write as follows:
12. ```php
add_shortcode( 'baztag', array( 'MyPlugin', 'wpdocs_baztag_func' ) );
class MyPlugin {
public static function wpdocs_baztag_func( $atts, $content = "" ) {
return "content = $content";
}
}
```
13. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%3Freplytocom%3D444%23feedback-editor-444)
14. [Skip to note 11 content](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#comment-content-3473)
15. [Denis Žoljom](https://profiles.wordpress.org/dingo_d/) [ 6 years ago ](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-3473)
16. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-3473)
Vote results for this note: 12[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-3473)
17. When adding `[add_shortcode()](https://developer.wordpress.org/reference/functions/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.
18. ```php
add_action( 'init', 'wpdocs_add_custom_shortcode' );
function wpdocs_add_custom_shortcode() {
add_shortcode( 'footag', 'wpdocs_footag_func' );
}
```
19. As described in the [plugins handbook](https://developer.wordpress.org/plugins/shortcodes/basic-shortcodes/#add-a-shortcode).
20. * There is currently (2020-12-23) no such recommendation in the [plugins handbook](https://developer.wordpress.org/plugins/shortcodes/basic-shortcodes/#add-a-shortcode)
nor in the [codex](https://codex.wordpress.org/Shortcode_API).
* [Bart Kuijper](https://profiles.wordpress.org/spartelfant/) [5 years ago](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-4681)
* @Denis Žoljom is correct. Even there is no recommendation in anywhere on WordPress
website but there are many short code functions and those functions will be
work correctly if there is a place to add short code properly. And from what
I look into WP core including ask from many AIs, they (AIs) and I recommend
use `init` hook. With this, other plugin can work with other functions about
short code and result correctly. Example: plugin A add some short code about
icon tag, my plug in B would like to override them so I may use `remove_shortcode()`
and then `add_shortcode()`.
* [vee](https://profiles.wordpress.org/okvee/) [4 months ago](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-7436)
21. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%3Freplytocom%3D3473%23feedback-editor-3473)
22. [Skip to note 12 content](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#comment-content-5089)
23. [Ahmad Karim](https://profiles.wordpress.org/ahmadkarim/) [ 5 years ago ](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-5089)
24. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-5089)
Vote results for this note: 5[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-5089)
25. Example of `add_shortcode` function that uses `get_template_part` function to
include a template.
26. ```php
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' );
```
27. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%3Freplytocom%3D5089%23feedback-editor-5089)
28. [Skip to note 13 content](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#comment-content-5379)
29. [nasifshuvo123](https://profiles.wordpress.org/nasifshuvo123/) [ 5 years ago ](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-5379)
30. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-5379)
Vote results for this note: 5[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-5379)
31. For wppb plugin boilerplate I add code to define_public_hooks()
`$this->loader-
>add_action( 'init', $plugin_public, 'register_shortcodes' );`
32. Then in public folder, in class_public file I added:
33. ```php
public function register_shortcodes(){
add_shortcode( 'sample-shortcode','shortcode_function' );
function shortcode_function( ) {
return "Hello Shortcode";
}
}
```
34. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%3Freplytocom%3D5379%23feedback-editor-5379)
35. [Skip to note 14 content](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#comment-content-5691)
36. [Matthias Kittsteiner](https://profiles.wordpress.org/kittmedia/) [ 4 years ago ](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-5691)
37. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-5691)
Vote results for this note: 5[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-5691)
38. 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:
39. “Fatal error: Uncaught Error: Argument 1 passed to shortcode_callback() must be
of the type array, string given”
40. Use a check whether `$arguments` is not an array and if so, replace it with an
empty array:
41. ```php
function shortcode_callback( $attributes, string $content, string $shortcode ) {
if ( ! is_array( $attributes ) ) {
$attributes = [];
}
// do stuff
}
```
42. * 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](https://profiles.wordpress.org/dargus/) [2 years ago](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-6953)
* 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](https://profiles.wordpress.org/gerardreches/) [2 years ago](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-6954)
43. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%3Freplytocom%3D5691%23feedback-editor-5691)
44. [Skip to note 15 content](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#comment-content-6692)
45. [Xedin Unknown](https://profiles.wordpress.org/xedinunknown/) [ 3 years ago ](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-6692)
46. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-6692)
Vote results for this note: 3[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-6692)
47. ⚠️⚠️
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](https://github.com/WordPress/gutenberg/issues/18988).
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.
48. To go around this, as mentioned in [a comment](https://github.com/WordPress/gutenberg/issues/18394#issuecomment-552593461),
use the [`is_admin()`](https://developer.wordpress.org/reference/functions/is_admin/)
function to prevent computation on admin pages.
49. * 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](https://profiles.wordpress.org/webunraveling/) [2 years ago](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-6863)
50. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%3Freplytocom%3D6692%23feedback-editor-6692)
51. [Skip to note 16 content](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#comment-content-2464)
52. [Patrick Johanneson](https://profiles.wordpress.org/pjohanneson/) [ 8 years ago ](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-2464)
53. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-2464)
Vote results for this note: 2[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-2464)
54. Notes (from the Codex — [https://codex.wordpress.org/Function_Reference/add_shortcode#Notes](https://codex.wordpress.org/Function_Reference/add_shortcode#Notes))
55. * 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.
56. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%3Freplytocom%3D2464%23feedback-editor-2464)
57. [Skip to note 17 content](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#comment-content-6421)
58. [SpeakOut! Steve](https://profiles.wordpress.org/123host/) [ 3 years ago ](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-6421)
59. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-6421)
Vote results for this note: 1[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-6421)
60. When passing values via the shortcode e.g. `[myshortcode FooBar="one" SomethingElse
="two"]` the keys in the array are transformed to lowercase
61. The array passed to the callback function will be: `Array( foobar => "one", somethingelse
=> "two" )`
62. Don’t be like me and spend hours trying to figure out why the values weren’t being
passed.
63. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%3Freplytocom%3D6421%23feedback-editor-6421)
64. [Skip to note 18 content](https://developer.wordpress.org/reference/functions/add_shortcode/?output_format=md&src=bl-po#comment-content-5631)
65. [Sabbir Mia](https://profiles.wordpress.org/sabbir009/) [ 4 years ago ](https://developer.wordpress.org/reference/functions/add_shortcode/#comment-5631)
66. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-5631)
Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%23comment-5631)
67. $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)
68. ```php
/**
* Appends 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( '%s', $button_attrs['url'], do_shortcode( $content ) );
}
add_shortcode( 'test-button', 'button_callback' );
```
69. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F%3Freplytocom%3D5631%23feedback-editor-5631)
You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_shortcode%2F)
before being able to contribute a note or feedback.