How to build custom Shortcodes in WordPress

• How to lay out your code efficiently
• Basic Shortcode
• Shortcode with Attributes
• Enclosing Shortcode (Shortcode with Content)
• Nested Shortcodes

Shortcodes are a fantastic feature in WordPress that allows you to embed files or create objects that would normally require lots of complicated, ugly code in just one line. You can even create your own custom shortcodes tailored to your specific needs. This article will guide you through the creation of different types of shortcodes, accessing attributes, slots, and nesting shortcodes.

¶How to lay out your code efficiently

Before we begin it's important to ensure your code is laid out in an efficient way. We have a thorough guide on laying your WordPress code out nicely which we always recommend everyone reads before starting a theme or plugin.

Whenever we reference adding code to your functions.php file you should always require or include a file within functions.php rather than placing it in there directly in order to benefit from everything mentioned in our article.

¶Basic Shortcode

Let's start with a simple shortcode. This shortcode will output a simple string when invoked.

function hello_world_shortcode() {
    return 'Hello, World!';
}
add_shortcode( 'helloworld', 'hello_world_shortcode' );

The add_shortcode() function takes two parameters: the shortcode tag (the string used in the content to invoke the shortcode) and the callback function.

Do use that shortcode it's as simple a [helloworld] anywhere in a supported editor.

¶Shortcode with Attributes

Attributes in shortcodes allow you to add specific values that can modify the output of the shortcode. Here's an example of a shortcode that accepts attributes:

function welcome_message_shortcode( $atts ) {
    $atts = shortcode_atts( array(
        'name' => 'Guest'
    ), $atts, 'welcome' );

    return 'Welcome, ' . $atts['name'] . '!';
}
add_shortcode( 'welcome', 'welcome_message_shortcode' );

In the example above, shortcode_atts() is used to handle the attributes for the shortcode. This function merges user shortcode attributes with known attributes and fills in defaults when needed. The third parameter is the name of the shortcode. This is used to apply a filter: shortcode_atts_{$shortcode}.

To use this shortcode do something like:

[welcome name="Joe"]

¶Enclosing Shortcode (Shortcode with Content)

Enclosing shortcodes are useful when you want to apply some functionality around existing content. They are structured as an opening and closing pair.

function bold_shortcode( $atts , $content = null ) {
    return '<strong>' . $content . '</strong>';
}
add_shortcode( 'bold', 'bold_shortcode' );

In the example above, bold_shortcode wraps the enclosed content within <strong> tags.

To use:

[bold]My bold content here[/bold]

This is very similar to BBCode from times gone by that was used in many forums.

¶Nested Shortcodes

WordPress doesn't natively support nested shortcodes or a shortcode within a shortcode. However, it is possible to handle within your own shortcode code.

To allow shortcodes to be nested inside your shortcode, you will need to call do_shortcode() in your shortcode callback function.

function outer_shortcode( $atts , $content = null ) {
    return '<div>' . do_shortcode($content) . '</div>';
}
add_shortcode( 'outer', 'outer_shortcode' );

function inner_shortcode( $atts , $content = null ) {
    return '<strong>' . $content . '</strong>';
}
add_shortcode( 'inner', 'inner_shortcode' );

Example of this would be:

[outer][inner]Testing, 123...[/inner][/outer]

Tread with caution with this, as it can quickly get complex, and doesn't support an infinite number of nests.

Shortcodes are an essential part of WordPress, providing an easy way to enhance the functionality of your posts and pages. By creating custom shortcodes, you can encapsulate complex HTML, CSS, or JavaScript into an easy-to-use tag that can be added directly to the editor. With practice, shortcodes can become a powerful tool in your WordPress toolkit.