Shortcodes inside a shortcode - wordpress

Shortcodes inside a shortcode - wordpress

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Nested Shortcodes Require Explicit Parsing in WordPress

In WordPress, shortcodes are essentially text replacements that happen during the content rendering phase. When you write a shortcode handler like [start_employee] and return a string containing '<ul class="employee">' . $content . '</ul>', you are treating $content as plain text. This is why nested shortcodes often fail: the outer shortcode processes first, sees the inner shortcode tag as literal characters, and returns it without further processing.

To achieve the behavior where [start_employee] wraps multiple [employee] tags correctly, you must explicitly tell WordPress to parse the content inside your wrapper. The standard solution is to wrap the $content variable in do_shortcode().

Here is how the logic should look:

function start_employee( $atts ) {
    // Extract attributes if needed, or handle defaults here
    extract(shortcode_atts([], 'start_employee', $atts));

    // Get the content between the opening and closing shortcode tags
    $content = do_shortcode($this->content); 

    return '<ul class="employee">' . $content . '</ul>';
}
add_shortcode('start_employee', 'start_employee');

Wait, there is a subtle issue with that snippet above. In the context of a standard function hooked to add_shortcode, $this->content does not exist; that syntax belongs to class-based shortcodes or custom filters. When using a simple function, you cannot directly access the raw content string passed to the handler unless you use a specific pattern or leverage WordPress's internal parsing mechanisms differently.

The correct approach for a function-based shortcode is to rely on the fact that $content is already passed as an argument to the function when you define it as function start_employee( $atts, $content = null ). However, simply echoing $content won't trigger nested parsing if the outer handler returns HTML.

The key realization is that the content passed to [start_employee] is just a string. To make WordPress evaluate shortcodes inside that string, you must pass it through do_shortcode():

function start_employee( $atts, $content = null ) {
    // Ensure $content is treated as a shortcode block if provided
    if ( !empty($content) && strpos($content, '[') !== false ) {
        $parsed_content = do_shortcode($content);
    } else {
        $parsed_content = '';
    }

    return '<ul class="employee">' . $parsed_content . '</ul>';
}
add_shortcode('start_employee', 'start_employee');

By wrapping $content with do_shortcode(), you force WordPress to re-scan the string for any registered shortcode patterns before concatenating it into your final HTML output. This transforms [employee ...] tags inside the wrapper into their actual rendered HTML, preventing them from appearing as raw text in the browser.

Trade-offs and Considerations

Using do_shortcode() introduces a recursive parsing behavior. If your inner shortcode also returns HTML containing other shortcodes, you might need to handle that depth specifically, though usually one level of nesting is sufficient for most use cases like employee lists.

Another consideration is performance. Running do_shortcode() on every invocation adds a slight overhead because WordPress has to re-initialize the parsing environment. For high-traffic sites with complex nested structures, this might warrant caching strategies or refactoring into custom functions that don't rely on the shortcode system for internal logic.

Also, be mindful of attribute extraction. If your inner [employee] shortcode relies on attributes passed directly in the text like img="..", ensure your parser handles those correctly. Sometimes developers mistakenly try to parse the content manually using regex, which is fragile and prone to breaking with complex HTML. Relying on WordPress's built-in do_shortcode() is safer and more maintainable.

If you are building a plugin where this pattern appears frequently, consider encapsulating the logic in a class. Class-based shortcodes offer better control over $this->content, allowing you to manipulate the content buffer before returning it, which can simplify nested handling without needing extra do_shortcode() wrappers everywhere.

Ultimately, the difference between seeing raw text and rendered HTML lies in whether you explicitly trigger the shortcode parser on the inner string. Without do_shortcode(), WordPress assumes your return value is final HTML. With it, you enable a chain of rendering, allowing dynamic content generation within structured containers.

Our network