Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Explainers · Explainer

What Is a Shortcode in WordPress? A Plain Explanation

What Is a Shortcode in WordPress? A Plain Explanation

Short answer

A shortcode is a small tag in square brackets, such as [gallery], that WordPress replaces with content when the page loads. A plugin registers the tag with a function, and WordPress runs that function each time the tag appears.

Key takeaways

  • A shortcode is a tag in square brackets that WordPress replaces with content when the page loads.
  • Shortcodes have been part of WordPress since version 2.5.
  • WordPress ships with six built-in shortcodes: audio, caption, embed, gallery, playlist, and video.
  • A shortcode callback must return text and never print output directly.
  • If the plugin behind a shortcode is gone, the tag shows on the page as plain text.

What is a shortcode in WordPress?

A shortcode is a small tag in square brackets, such as [gallery], that WordPress replaces with content when the page loads.

You type the tag into a post or page instead of writing the code that builds the result. WordPress swaps the tag for the output when a reader opens the page, so a nine-character tag can produce a full photo gallery.

Shortcodes have been part of WordPress since version 2.5, when they were added as a way to put macros into post content. They still work in the block editor today, next to blocks that do similar jobs.

Shortcodes run in posts, pages, and custom post types alike. Our guide to posts vs pages in WordPress explains how those two content types differ.

How does a shortcode work?

A plugin registers a shortcode tag with a function, and WordPress runs that function whenever the tag appears in content.

The developer registers the tag with add_shortcode(), giving the tag name and the callback function to run. The Plugin Handbook page on basic shortcodes shows the pattern: add_shortcode( 'wporg', 'wporg_shortcode' ) links the [wporg] tag to the wporg_shortcode function.

When WordPress shows the post, it scans the content for registered tags and replaces each one with what its callback returns. The callback must return text; it must never print output directly, or the output lands at the top of the page instead of where the tag stood.

The do_shortcode() function does the scanning, and the developer reference notes that it was introduced in version 2.5.0. It lives in wp-includes/shortcodes.php and takes the content plus an optional flag to skip shortcodes inside HTML elements.

What shortcodes come with WordPress?

WordPress ships with six built-in shortcodes: [audio], [caption], [embed], [gallery], [playlist], and [video].

The WordPress Codex lists all six as included with WordPress, with plugins able to add more through the Shortcode API. [gallery] builds an image gallery from the images attached to a post, and [gallery id="123" size="medium"] picks one gallery and a size.

ShortcodeWhat it showsExample
[gallery]Image gallery[gallery ids="1,2,3" columns="3"]
[audio]Audio player[audio src="song.mp3"]
[video]Video player[video src="clip.mp4"]
[caption]Caption around content[caption]A photo[/caption]
[playlist]Audio or video playlist[playlist type="video"]
[embed]Embedded item with set size[embed width="600"]

The [playlist] shortcode has been in core since version 3.9.0, and it takes a type of audio or video, with audio as the default. Its order defaults to ascending, and its style can be light or dark.

Plugins add their own shortcodes on top of these six. A form plugin adds a shortcode that prints a form, and a shop plugin adds shortcodes for carts and checkouts. WordPress.com lists dozens more on its own platform, such as [youtube], [contact-form], and [display-posts], in its shortcodes guide.

How do you add a shortcode to a post or page?

Add a Shortcode block and type or paste the shortcode into its box.

In the block editor, click the add block button, find “Shortcode” in the Widgets section, and click it. You can also type /shortcode on a new line and press Enter. The WordPress.org Shortcode block guide notes that the block has no settings of its own in the toolbar or sidebar.

Type the shortcode into the box, including the square brackets, then save or publish. The editor shows the tag itself, while the published page shows the result. Preview the page to check the output before you share it.

In the classic editor, you can type a shortcode straight into the post body. Shortcodes also run in text widgets since version 4.9, so the same tag works in a sidebar. Developers can run a shortcode in a theme template by calling do_shortcode() in PHP.

Blocks now cover much of what shortcodes once did, but shortcodes still suit small reusable jobs. Our guide to Gutenberg vs page builders compares the block editor with the main page builders.

What are shortcode attributes?

Attributes are options you write inside the opening tag, such as ids="1,2,3" in [gallery ids="1,2,3"].

Attributes let one shortcode do many jobs. [gallery] alone shows the post's attached images, while [gallery ids="225,132,611,320" columns="3" orderby="title" order="ASC"] shows four chosen images in three columns sorted by title.

WordPress hands the attributes to the callback as an array called $atts, along with the enclosed content and the tag name. Attribute names are always changed to lowercase before they reach the callback, so ID="5" arrives as id. Values keep their original case.

Use shortcode_atts() in the callback to merge the given attributes with defaults, so a missing attribute falls back to a sane value. Keep attribute names short and clear, since your readers may need to type them.

What is the difference between a self-closing and an enclosing shortcode?

A self-closing shortcode stands alone, while an enclosing shortcode wraps content between an opening and a closing tag.

[gallery] is self-closing: it needs no closing tag and takes all its options as attributes. [caption] is enclosing: it wraps content, as in [caption]A photo of the lake[/caption], and the callback receives the wrapped text as $content.

The Plugin Handbook notes that the parser makes a single pass over the content. A shortcode nested inside the content of another shortcode will not run on its own. To support nesting, the callback must call do_shortcode() on its final return value.

One more limit applies: the parser cannot mix the enclosing and non-enclosing forms of the same tag. Writing [wporg] text [wporg]more text[/wporg] makes WordPress treat the whole stretch as one enclosing shortcode, not two separate ones.

What happens when the plugin behind a shortcode is gone?

The shortcode stays in the post as plain text, brackets and all.

Every shortcode outside the six built-ins comes from a plugin. If you deactivate or delete that plugin, WordPress has no callback for the tag, so it leaves the text alone. Readers see [contact-form] on the page instead of a form.

The Codex explains that WordPress treats the whole shortcode, its attributes, and its enclosed content as normal text in that case, and keeps the special characters in the output. The content itself is safe; only the display breaks.

Before you remove a plugin, search your site for its shortcodes and replace them or keep the plugin active. A quick search of the database or a find-and-replace plugin will show every post that uses the tag.

What mistakes should you avoid with shortcodes?

The most common mistake is typing a shortcode into a Paragraph block, where it shows as plain text.

Shortcodes need their own Shortcode block in the block editor. A Paragraph block will not run them, so the tag prints on the page instead of the result. The same applies to widgets: use a Shortcode block in the widget area.

A second mistake is forgetting the closing tag on an enclosing shortcode. An unclosed [caption] will swallow the rest of the post into the caption, so check that every opening tag has its match.

A third mistake is using a tag name that another plugin already uses. The developer reference warns that only one callback can sit behind a tag, and the one loaded last wins. Prefix your own tags with something unique, such as your site name, to avoid a clash.

A fourth mistake is writing a callback that prints instead of returning. The add_shortcode() reference states plainly that the function called by a shortcode should never produce output of any kind, and must return the text that replaces the tag.

Finally, do not trust shortcode attributes blindly. Attribute values come from the post content, so a callback should clean them before use. The developer guide on plugin security covers the sanitize and escape steps for this.

WooCommerce relies on shortcodes for its cart and checkout pages, so if you run a store, read our guide to WooCommerce cart and checkout blocks vs shortcode before you switch anything.

Our guide to how to create a custom block in WordPress shows the block-based path for new features.

Frequently asked questions

Are shortcodes dead now that blocks exist?

No, shortcodes still work in the block editor through the Shortcode block. Blocks cover many of the same jobs with a visual preview, so new features often ship as blocks, but thousands of plugins still rely on shortcodes and WordPress has no plan to remove them.

Why does my shortcode show as plain text?

First check that the plugin behind the shortcode is installed and active, since a missing plugin leaves the tag as plain text. Next confirm you used a Shortcode block, not a Paragraph block, and that the tag name and attributes match the plugin docs exactly.

Can I put a shortcode inside another shortcode?

Yes, but only if the shortcode supports it. The parser makes a single pass, so a shortcode inside another shortcode will not run unless the outer callback calls do_shortcode() on its return value. Check the plugin docs to see if nesting is supported.

How do I show a shortcode as text without running it?

Type double brackets around it, as in [[gallery]], and WordPress will show [gallery] as text instead of running it. This only works for shortcodes that are currently registered on your site.

Can I use a shortcode in a widget?

Yes. Add a Shortcode block in the widget area, or use the Shortcode block in the block-based Widgets screen. Shortcodes have run in text widgets since WordPress 4.9, so the same tag works in a sidebar as in a post.

When should I use a shortcode instead of a block?

Shortcodes are faster to add and suit simple reusable output such as a form or a gallery. Blocks show a live preview and suit layout and design work. For a new feature, a block is usually the better pick, while a shortcode is fine for a small job a plugin already provides.

Sources

  1. Basic Shortcodes WordPress Developer Resources
  2. Enclosing Shortcodes WordPress Developer Resources
  3. Shortcode WordPress Codex
  4. Shortcode block WordPress.org
  5. Shortcode block in WordPress WordPress.com Support

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.