WordPress Shortcode

What Is a WordPress Shortcode?

A WordPress shortcode is a tag in square brackets, such as [gallery] or [contact-form id="12"], that WordPress replaces with the output of a PHP function when the content is displayed. It lets editors insert dynamic or complex features into a post without writing code.

The Shortcode API was added in WordPress 2.5, long before blocks existed, and it is still part of core. WordPress ships with a few of its own, including [gallery], [caption], [audio], [video], [playlist] and [embed], and many plugins use shortcodes to place forms, sliders or product grids. In the block editor, shortcodes are added with the dedicated Shortcode block, although blocks have largely become the preferred way to build these features.

Why Shortcodes Matter

Even on modern sites, shortcodes are everywhere, so it helps to understand what they do well and where they fall short.

• Simple reuse: One function can output the same feature anywhere you can type text: posts, pages, widgets and many theme options.
• Dynamic output: Content is generated at render time, so a shortcode listing upcoming events always shows current data.
• Legacy compatibility: Older content and many page builders depend on shortcodes, so they need to keep working during redesigns and migrations.
• Weak editing experience: Editors see a bracketed tag instead of a preview, and a typo in an attribute fails silently.
• Content lock-in: If the plugin that registers a shortcode is removed, the raw tag appears on the live page as plain text.

How a Shortcode Works

1. Registration: A plugin or theme calls add_shortcode( 'tag', 'callback' ), connecting a tag name to a PHP function.
2. Parsing: When content is displayed, WordPress runs it through do_shortcode(), finds registered tags and calls their callbacks.
3. Attributes: Values like [team count="4"] are passed to the callback as an array; shortcode_atts() merges them with defaults and filters out unknown keys.
4. Enclosing content: A shortcode can wrap content, as in [note]Text[/note], and the callback receives that inner text as a second argument.
5. Return, do not echo: The callback must return its HTML as a string. Echoing output prints it in the wrong place on the page, usually above the content.

Common Shortcode Mistakes

• Echoing instead of returning: The most frequent bug, causing output to appear at the top of the page.
• Unescaped output: Printing attribute values without esc_html() or esc_attr(), which opens the door to cross-site scripting by anyone who can edit content.
• Generic tag names: Using names like [button] that collide with other plugins. Prefix tags with a project-specific name.
• Registering in the theme: Defining shortcodes in functions.php, so switching themes leaves raw tags all over the site.
• Loading assets on every page: Enqueuing a shortcode's CSS and JavaScript sitewide instead of only where it is used.

Best Practices for Shortcodes

• Put them in a plugin: Register shortcodes in a site-specific or feature plugin so they survive design changes.
• Validate and escape everything: Sanitize attributes on the way in and escape on the way out.
• Document each tag: List the available attributes, defaults and an example for editors.
• Prefer blocks for new features: A custom block gives editors a live preview, proper controls and structured settings. Our Gutenberg editor entry explains how blocks work.
• Use shortcodes where blocks do not reach: They remain useful in classic widgets, some theme settings and when calling do_shortcode() from template code.
• Audit before removing plugins: Search the database for a plugin's tags before deactivating it, so no raw shortcodes are left visible.

Shortcodes at PerfectPixels

Through our custom WordPress plugin development, we build features as blocks by default and add a shortcode when a client needs it in places blocks cannot go or for compatibility with existing content. During redesigns and migrations we also inventory legacy shortcodes, often left by old page builders, and convert or retire them so nothing breaks on launch.

Frequently Asked Questions

Are shortcodes still supported in WordPress?

Yes. The Shortcode API is part of WordPress core and works in the block editor through the Shortcode block. They are no longer the recommended approach for new editor-facing features, but they are not deprecated.

Why is a shortcode showing as text on my page?

The function that handles it is not registered, usually because the plugin or theme that provided it was deactivated or removed. It can also happen if the shortcode is placed somewhere WordPress does not process shortcodes, such as some custom fields.

Should I convert my shortcodes to blocks?

For features your editors use often, yes: blocks are easier to use and show a preview. For rarely used or legacy content, it is often fine to leave shortcodes in place as long as the plugin behind them is maintained.

Related Resources

• Gutenberg Editor
• WordPress Plugins
• Page Builder
• WordPress Plugin Development

Further reading: Shortcodes — WordPress Developer Resources.