WordPress Shortcodes API Overview
The Shortcodes API provides a bbcode-like tag system for WordPress. It allows developers to create custom macros that users can insert into content using bracket notation. The parser is based on the Textpattern tag parser.
Since: WordPress 2.5.0
Source: wp-includes/shortcodes.php
Shortcode Syntax
WordPress supports three shortcode formats:
Self-Closing Shortcodes
[shortcode]
[shortcode /]Both forms are equivalent. The trailing slash is optional.
Shortcodes with Attributes
[shortcode foo="bar" baz="bing"]
[shortcode foo="bar" baz="bing" /]Attributes support three quote styles:
- Double quotes:
foo="bar" - Single quotes:
foo='bar' - No quotes:
foo=bar(value cannot contain spaces)
Attribute names are case-insensitive and converted to lowercase.
Enclosing Shortcodes
[shortcode]content here[/shortcode]
[shortcode foo="bar"]content here[/shortcode]The content between opening and closing tags is passed to the callback as $content.
Attribute Parsing
The attribute parser handles several formats:
| Format | Example | Result |
|---|---|---|
| Double-quoted | name="value" | ['name' => 'value'] |
| Single-quoted | name='value' | ['name' => 'value'] |
| Unquoted | name=value | ['name' => 'value'] |
| Positional (quoted) | "value" | [0 => 'value'] |
| Positional (unquoted) | value | [0 => 'value'] |
Important behaviors:
- Attribute names are lowercased automatically
- Non-breaking spaces and zero-width spaces are normalized to regular spaces
- Unclosed HTML elements in attribute values are rejected (value becomes empty string)
- C-style escape sequences are processed via
stripcslashes()
Shortcode Nesting
WordPress shortcodes have limited nesting support. The core parser does not automatically process nested shortcodes—the outer shortcode’s callback must explicitly call do_shortcode() on its content.
How to Support Nesting
function my_outer_shortcode( $atts, $content = null ) {
// Process any nested shortcodes in $content
$content = do_shortcode( $content );
return '<div class="outer">' . $content . '</div>';
}
add_shortcode( 'outer', 'my_outer_shortcode' );