Complete reference for all functions in the WordPress Shortcodes API.

---

Registration Functions

add_shortcode()

Registers a new shortcode handler.

add_shortcode( string $tag, callable $callback )

Parameters:

• $tag (string) — Shortcode tag to register
• $callback (callable) — Function to call when shortcode is found

Callback Signature:

function my_shortcode_handler( array $atts, ?string $content, string $tag ): string

• $atts — Parsed attributes array
• $content — Content between opening/closing tags (null if self-closing)
• $tag — The shortcode tag name

Returns: void

Since: 2.5.0

Example:

function greeting_shortcode( $atts, $content = null ) {
    $atts = shortcode_atts( [
        'name' => 'World',
    ], $atts, 'greeting' );
    
    return '<p>Hello, ' . esc_html( $atts['name'] ) . '!</p>';
}
add_shortcode( 'greeting', 'greeting_shortcode' );

// Usage: [greeting name="Alice"] → <p>Hello, Alice!</p>

Invalid Names:

// These will trigger _doing_it_wrong():
add_shortcode( '', $callback );           // Empty name
add_shortcode( 'my tag', $callback );     // Contains space
add_shortcode( 'my[tag', $callback );     // Contains [
add_shortcode( 'my/tag', $callback );     // Contains /

---

remove_shortcode()

Removes a registered shortcode.

remove_shortcode( string $tag )

Parameters:

• $tag (string) — Shortcode tag to remove

Returns: void

Since: 2.5.0

Example:

// Remove WordPress core gallery shortcode
remove_shortcode( 'gallery' );

// Replace with custom implementation
add_shortcode( 'gallery', 'my_custom_gallery' );

---

remove_all_shortcodes()

Removes all registered shortcodes.

remove_all_shortcodes()

Returns: void

Since: 2.5.0

Example:

// Disable all shortcodes for API output
remove_all_shortcodes();
echo do_shortcode( $content ); // Returns content unchanged

Warning: This removes ALL shortcodes including core WordPress ones like , , , etc.

---

Detection Functions

shortcode_exists()

Checks if a shortcode is registered.

shortcode_exists( string $tag ): bool

Parameters:

• $tag (string) — Shortcode tag to check

Returns: true if shortcode exists, false otherwise

Since: 3.6.0

Example:

if ( ! shortcode_exists( 'my_shortcode' ) ) {
    add_shortcode( 'my_shortcode', 'my_handler' );
}

---

has_shortcode()

Checks if content contains a specific shortcode.

has_shortcode( string $content, string $tag ): bool

Parameters:

• $content (string) — Content to search
• $tag (string) — Shortcode tag to find

Returns: true if shortcode is found (including nested), false otherwise

Since: 3.6.0

Example:

// Conditionally enqueue scripts
if ( has_shortcode( $post->post_content, 'gallery' ) ) {
    wp_enqueue_script( 'gallery-lightbox' );
}

Note: This function recurses into nested shortcode content to find matches.

---

get_shortcode_tags_in_content()

Returns all registered shortcode tags found in content.

get_shortcode_tags_in_content( string $content ): string[]

Parameters:

• $content (string) — Content to search

Returns: Array of shortcode tag names found

Since: 6.3.2

Example:

$content = '[audio src="file.mp3"][/audio] [foo] [gallery ids="1,2,3"]';
$tags = get_shortcode_tags_in_content( $content );
// Returns: ['audio', 'gallery'] (if 'foo' is not registered)

Note: Only returns tags that are actually registered. Unregistered shortcode-like text is ignored. Recurses into nested content.

---

Processing Functions

do_shortcode()

Processes shortcodes in content.

do_shortcode( string $content, bool $ignore_html = false ): string

Parameters:

• $content (string) — Content to process
• $ignore_html (bool) — Skip shortcodes inside HTML elements (default: false)

Returns: Content with shortcodes replaced by their output

Since: 2.5.0

Example:

// Process shortcodes in widget text
$output = do_shortcode( $widget_text );

// Process shortcodes but ignore those in HTML attributes
$output = do_shortcode( $content, true );

Automatic Usage:

WordPress automatically applies do_shortcode to:

• the_content filter (priority 11)
• widget_text_content filter
• Various other content areas depending on theme/plugins

---

apply_shortcodes()

Alias for do_shortcode().

apply_shortcodes( string $content, bool $ignore_html = false ): string

Since: 5.4.0

Introduced for naming consistency with other WordPress functions like apply_filters().

---

do_shortcodes_in_html_tags()

Processes shortcodes found inside HTML elements.

do_shortcodes_in_html_tags( string $content, bool $ignore_html, array $tagnames ): string

Parameters:

• $content (string) — Content to process
• $ignore_html (bool) — If true, encode all brackets in HTML
• $tagnames (array) — List of shortcode tags to process

Returns: Processed content

Since: 4.2.3

Internal: This is primarily used internally by do_shortcode().

Behavior:

• Normalizes bracket entities ([ → [)
• Processes shortcodes in unquoted attributes directly
• Processes shortcodes in quoted attributes with KSES sanitization
• Encodes remaining brackets to prevent interference

---

do_shortcode_tag()

Callback function for shortcode regex replacement.

do_shortcode_tag( array $m ): string

Parameters:

• $m (array) — Regex match array from get_shortcode_regex()

Returns: Shortcode output or original text if escaped

Since: 2.5.0

Access: Private (used internally)

Match Array Structure:

Index	Content
$m[0]	Full match
$m[1]	Optional [ for escaping
$m[2]	Shortcode name
$m[3]	Attributes string
$m[4]	Self-closing /
$m[5]	Enclosed content
$m[6]	Optional ] for escaping

---

Attribute Functions

shortcode_parse_atts()

Parses shortcode attributes string into an array.

shortcode_parse_atts( string $text ): array

Parameters:

• $text (string) — Attribute string from shortcode

Returns: Associative array of attributes. Always returns array (since 6.5.0).

Since: 2.5.0

Example:

$atts = shortcode_parse_atts( 'foo="bar" baz='qux' id=123 "positional"' );
// Returns:
// [
//     'foo' => 'bar',
//     'baz' => 'qux',
//     'id'  => '123',
//     0     => 'positional',
// ]

Parsing Rules:

• Attribute names are lowercased
• Supports double quotes, single quotes, or no quotes
• Positional values get numeric keys
• Non-breaking spaces normalized to regular spaces
• C-style escapes processed (n, ", etc.)
• Unclosed HTML in values is rejected

---

shortcode_atts()

Merges user attributes with defaults.

shortcode_atts( array $pairs, array $atts, string $shortcode = '' ): array

Parameters:

• $pairs (array) — Default attribute values
• $atts (array) — User-provided attributes
• $shortcode (string) — Shortcode name (enables filtering)

Returns: Merged attributes (only keys from $pairs are included)

Since: 2.5.0

Example:

function my_shortcode( $atts ) {
    $atts = shortcode_atts( [
        'id'    => 0,
        'class' => 'default',
        'title' => '',
    ], $atts, 'my_shortcode' );
    
    // $atts now has guaranteed keys with defaults filled in
    return sprintf(
        '<div id="%d" class="%s">%s</div>',
        intval( $atts['id'] ),
        esc_attr( $atts['class'] ),
        esc_html( $atts['title'] )
    );
}

Important: Unknown attributes (not in $pairs) are silently discarded.

---

get_shortcode_atts_regex()

Returns the regex pattern for parsing attributes.

get_shortcode_atts_regex(): string

Returns: Regex pattern string

Since: 4.4.0

Pattern Matches:

1. name="value" (double-quoted)
2. name='value' (single-quoted)
3. name=value (unquoted)
4. "value" (positional double-quoted)
5. 'value' (positional single-quoted)
6. value (positional unquoted)

---

Stripping Functions

strip_shortcodes()

Removes all shortcode tags from content.

strip_shortcodes( string $content ): string

Parameters:

• $content (string) — Content to strip

Returns: Content with shortcodes removed (content between tags is also removed)

Since: 2.5.0

Example:

$content = 'Hello [gallery ids="1,2,3"] World [caption]Photo';
echo strip_shortcodes( $content );
// Output: "Hello  World "

Use Cases:

• Generating excerpts
• Search indexing
• Plain text output

---

strip_shortcode_tag()

Callback for stripping individual shortcode matches.

strip_shortcode_tag( array $m ): string|false

Parameters:

• $m (array) — Regex match array

Returns: Empty string (shortcode removed) or content for escaped shortcodes

Since: 3.3.0

Access: Private (used internally by strip_shortcodes())

---

Regex Functions

get_shortcode_regex()

Returns the regex pattern for finding shortcodes.

get_shortcode_regex( ?array $tagnames = null ): string

Parameters:

• $tagnames (array|null) — Specific tags to match (default: all registered)

Returns: Regex pattern string (without delimiters)

Since: 2.5.0, 4.4.0 added $tagnames parameter

Example:

// Match all registered shortcodes
$pattern = get_shortcode_regex();
preg_match_all( "/$pattern/", $content, $matches );

// Match only specific shortcodes
$pattern = get_shortcode_regex( [ 'gallery', 'audio' ] );

Warning: The regex is complex. Changes to it must be synchronized with:

• do_shortcode_tag()
• strip_shortcode_tag()
• shortcode_unautop()
• shortcode.js (JavaScript equivalent)

---

Utility Functions

unescape_invalid_shortcodes()

Restores bracket characters after processing.

unescape_invalid_shortcodes( string $content ): string

Parameters:

• $content (string) — Content with encoded brackets

Returns: Content with brackets restored

Since: 4.2.3

Conversions:

• [ → [
• ] → ]

Purpose: Preserves IE conditional comments like <!--[if IE]> that would otherwise be broken by shortcode processing.

---

_filter_do_shortcode_context()

Internal filter for attachment image context.

_filter_do_shortcode_context(): string

Returns: 'do_shortcode'

Since: 6.3.0

Access: Private

Purpose: When wp_get_attachment_image() is called during shortcode rendering, this filter sets the context to 'do_shortcode' so themes/plugins can distinguish shortcode context from template rendering.

---

Function Quick Reference

Function	Purpose	Since
add_shortcode()	Register shortcode	2.5.0
remove_shortcode()	Unregister shortcode	2.5.0
remove_all_shortcodes()	Clear all shortcodes	2.5.0
shortcode_exists()	Check if registered	3.6.0
has_shortcode()	Check content for tag	3.6.0
get_shortcode_tags_in_content()	List tags in content	6.3.2
do_shortcode()	Process shortcodes	2.5.0
apply_shortcodes()	Alias for do_shortcode	5.4.0
shortcode_parse_atts()	Parse attribute string	2.5.0
shortcode_atts()	Merge with defaults	2.5.0
strip_shortcodes()	Remove all shortcodes	2.5.0
get_shortcode_regex()	Get matching pattern	2.5.0
get_shortcode_atts_regex()	Get attribute pattern	4.4.0