What are WordPress shortcodes?

WordPress shortcodes are small pieces of code, wrapped in square brackets like [gallery], that let you add dynamic content and complex functionality to your posts, pages, and widgets without writing a single line of PHP. Instead of hand-coding a form, a slideshow, or an embedded video every time you need one, you simply drop in a shortcode and WordPress does the heavy lifting behind the scenes.

WordPress is built to be approachable for non-developers, and shortcodes are one of the clearest examples of that philosophy in action. They turn functionality that would otherwise require custom code into something anyone can use with a bit of bracketed text. This article covers what shortcodes are, how they work, and how to use them effectively on your site.

What Are WordPress Shortcodes?

A shortcode is a specific tag, enclosed in square brackets, that WordPress recognizes and replaces with dynamic content when a page is rendered. For example, typing [gallery] into a post will output a fully functional image gallery, even though what you typed was just a short piece of text.

Shortcodes were introduced in WordPress 2.5 as a way to give users an easy shorthand for embedding functions that would otherwise require editing template files or writing PHP directly into a post. They're built on top of the WordPress Shortcode API, which handles parsing the bracketed tag and running the corresponding function.

Why Are WordPress Shortcodes Important?

Shortcodes bridge the gap between complex functionality and ease of use. They let you:

• Add features like contact forms, sliders, and galleries without editing theme files.
• Reuse the same piece of functionality across multiple posts and pages with different settings.
• Keep your content editable by anyone on your team, not just developers.
• Extend your site's capabilities through plugins that register their own shortcodes.

How Do WordPress Shortcodes Work?

Behind the scenes, a shortcode is just a PHP function that has been registered with WordPress using the add_shortcode() function. When WordPress renders your content, it scans for bracketed tags, matches them against registered shortcodes, and replaces each tag with the output of its corresponding function.

1. Registration: A shortcode is registered with a unique tag name and a callback function, for example add_shortcode('my_shortcode', 'my_shortcode_function').

2. Parsing: When a post or page is loaded, WordPress's Shortcode API scans the content for bracketed tags that match registered shortcodes.

3. Execution: For each match, WordPress runs the associated callback function, optionally passing in any attributes included in the tag.

4. Output: The callback function returns HTML (or other content), which replaces the shortcode tag before the page is displayed to visitors.

Types of Shortcodes

Shortcodes generally come in two forms:

• Self-closing shortcodes: These don't wrap around any content. Example: [gallery ids="1,2,3"].
• Enclosing shortcodes: These wrap around a block of content, similar to an HTML tag. Example: [caption]An image caption[/caption].

Shortcode Attributes

Many shortcodes accept attributes that let you customize their behavior, written as key="value" pairs inside the brackets. For example:

[gallery ids="12,15,18" columns="3"]

Here, ids specifies which images to include, and columns controls the layout of the gallery.

Common Built-In WordPress Shortcodes

WordPress core ships with several shortcodes out of the box:

[gallery]: Displays a gallery of images that have been uploaded to a post or page.

[caption]: Wraps an image (or other content) with a styled caption.

[audio]: Embeds an audio player for a specified file.

[video]: Embeds a video player for a specified file.

[embed]: Embeds content from supported external sites, such as YouTube or Twitter, by simply pasting a URL.

[playlist]: Displays a playlist of audio or video files.

Shortcodes Provided by Plugins

Many plugins register their own shortcodes to expose their features directly inside the content editor:

Contact Form 7: Uses a unique shortcode, like [contact-form-7 id="123" title="Contact form"], to embed a specific form anywhere on your site.

WooCommerce: Provides shortcodes such as [products] and [add_to_cart] to display products and purchase buttons outside the default shop pages.

Yoast SEO: Offers a [yoast-breadcrumb] shortcode to display breadcrumb navigation.

Elementor and other page builders: Often generate shortcodes internally to render specific widgets or templates inside posts.

How to Use a WordPress Shortcode

Adding a shortcode to your content is straightforward:

1. In the Block Editor (Gutenberg):

   • Add a Shortcode block from the block inserter.
   • Paste the shortcode into the block.

2. In the Classic Editor:

   • Simply type or paste the shortcode directly into the content area.

3. In Widgets:

   • Add a Shortcode widget (or a Custom HTML widget) to a widget-ready area and paste the shortcode in.

4. In Theme Files:

   • Use the do_shortcode() function to render a shortcode from within a PHP template file, for example: <?php echo do_shortcode('[gallery]'); ?>.

How to Create a Custom Shortcode

If you want functionality that no existing shortcode provides, you can create your own by adding code to your theme's functions.php file or a custom plugin:

function my_custom_shortcode() {
    return '<p>This content was generated by a shortcode!</p>';
}
add_shortcode('my_shortcode', 'my_custom_shortcode');

Once registered, typing [my_shortcode] anywhere in your content will output the returned HTML. You can extend this by accepting attributes:

function my_greeting_shortcode($atts) {
    $atts = shortcode_atts(
        array('name' => 'friend'),
        $atts
    );
    return '<p>Hello, ' . esc_html($atts['name']) . '!</p>';
}
add_shortcode('greeting', 'my_greeting_shortcode');

Using [greeting name="Sajjad"] would then output "Hello, Sajjad!".

Best Practices for Using Shortcodes

Don't overuse them: Relying on too many shortcodes for basic layout can make content harder to maintain, especially if you later switch themes or plugins.

Keep a reference: Note down which shortcodes your plugins provide and what attributes they accept, since these aren't always obvious from the editor alone.

Be cautious when deactivating plugins: If a plugin that registers a shortcode is deactivated, any shortcode instances left in your content will display as raw bracketed text instead of the intended output.

Test after updates: Plugin and theme updates can occasionally change a shortcode's expected attributes, so it's worth checking your key pages after major updates.

Use the Shortcode block wisely: In the block editor, prefer native blocks when one exists for what you need, and reserve shortcodes for functionality that doesn't yet have a block equivalent.

Troubleshooting Common Shortcode Issues

Shortcode Displays as Plain Text: This usually means the plugin or theme that registers the shortcode is inactive, or the shortcode name was typed incorrectly.

Shortcode Doesn't Render Inside Widgets: Some older widget areas don't automatically process shortcodes. Adding add_filter('widget_text', 'do_shortcode'); to your theme's functions.php file resolves this in most cases.

Shortcode Conflicts: If two plugins register a shortcode with the same tag name, only one will work as expected. Check your plugin documentation or rename one of the shortcodes if you have access to the code.

Content Formatting Issues: Occasionally, WordPress's automatic paragraph formatting (wpautop) can insert unwanted <p> tags around a shortcode's output. Wrapping the shortcode's return value carefully, or using do_shortcode() outside of the_content filter, can help avoid this.

---

FAQ: WordPress Shortcodes

---

Conclusion

WordPress shortcodes are a simple but powerful way to add dynamic functionality to your content without touching a template file. Whether you're using the handful of shortcodes built into WordPress core, the ones provided by your favorite plugins, or writing your own custom shortcode for a specific need, they let you keep your workflow fast and your content flexible.

As you build out your site, keep a note of which shortcodes are available to you and what attributes they support, and always double-check your pages after deactivating a plugin or switching themes. With a good grasp of how shortcodes work, you can add rich functionality to your WordPress site without writing a line of extra code in your posts.