What Is a WordPress Shortcode? Simple Examples and Common Mistakes

You open a WordPress page and see something like [contact-form-7 id="123"] sitting in the content. Or you copy a shortcode from a plugin and paste it into your post, but the published page just shows the raw tag as text instead of anything useful.

These are the two most common shortcode moments for beginners: noticing them for the first time, and wondering why they are not working.

This guide explains what shortcodes are, where to place them, and what causes them to fail.

Short Answer

A WordPress shortcode is a short code tag wrapped in square brackets, such as [gallery] or [contact-form-7 id="123"]. When WordPress publishes a page, it scans the content for these tags and replaces each one with the actual output it represents. That output might be a photo gallery, a contact form, a product grid, a booking widget, or anything a plugin is set up to produce.

You write the tag. WordPress (or a plugin) replaces it with the real content.

Shortcodes have existed in WordPress since version 2.5, released in 2008. They were designed to let non-developers add dynamic functionality to posts and pages without writing code directly, according to the WordPress shortcodes documentation.

What It Means in Practice

Think of a shortcode as a labeled placeholder. When you write [gallery] inside a page, you are telling WordPress: "put a photo gallery here." WordPress processes that instruction when the page loads and swaps the tag out for the actual gallery.

This is useful in a few specific situations:

• Embedding plugin features into a page. Contact forms, booking widgets, sliders, product listings, and membership content are all typically added through shortcodes.
• Reusing the same output in multiple places. You can paste the same shortcode on five different pages. The output stays in sync because it is managed in one place (the plugin settings or media library), not in the page content itself.
• Adding dynamic content HTML alone cannot produce. A static page in HTML cannot display "today's available appointment slots" or "logged-in user's order history." A shortcode connected to a plugin can.

Shortcodes are not the only way to add this kind of content. The WordPress block editor lets you insert many of the same features through dedicated blocks. But shortcodes are still widely used, especially with older plugins and existing content.

How It Works in WordPress

The classic editor

In the classic editor (the one that uses a toolbar similar to a word processor), you can type or paste a shortcode directly into the post body. WordPress processes it on save and displays the output when the page is viewed.

The block editor (Gutenberg)

The block editor is the default in all modern WordPress installations. This is where many beginners run into trouble.

The Shortcode block is the dedicated, recommended place for shortcodes in the block editor. Whether a shortcode processes correctly inside other block types depends on the plugin, the theme, and the WordPress version in use. Using the Shortcode block avoids that uncertainty.

To add a shortcode using the Shortcode block:

1. Click the + button to add a new block.
2. Search for "Shortcode" and select the Shortcode block.
3. Paste your shortcode into the block field.
4. Save or update the page, then preview the page on the front end to confirm the output is correct.

The Shortcode block is built into WordPress and requires no additional plugin. For more background on navigating the WordPress editor and admin area, the WordPress admin dashboard beginner guide covers the key screens and menus.

Widgets (sidebar and footer areas)

Shortcodes also work inside text-based widgets in your sidebar, footer, or other widget areas.

In the classic Widgets screen (Appearance > Widgets), you can add a Text widget and paste a shortcode inside it. WordPress processes shortcodes in Text widgets since version 4.9.

In the block-based Widgets editor (used in some themes), you need to add a Shortcode block inside the widget area, just as you would in the block editor.

Theme template files (for developers only)

Shortcodes are not processed automatically inside PHP template files (like single.php or page.php). If you paste a shortcode into a template file as a string, it prints literally. To process it, a developer needs to wrap it in the do_shortcode() function:

echo do_shortcode('[gallery]');

This is a developer task. If you are not modifying theme files, you will not encounter this situation.

Common Examples of WordPress Shortcodes

WordPress includes a small set of built-in shortcodes. Most shortcodes come from plugins you install.

Built-in WordPress shortcodes

Plugin-generated shortcodes

Most shortcodes you encounter come from plugins. Here are common examples:

Contact Form 7 (one of the most widely installed plugins on WordPress.org):

[contact-form-7 id="123" title="Contact form 1"]

This displays the form with that specific ID on any page where you place it.

WooCommerce (used for online stores):

[woocommerce_cart]
[woocommerce_checkout]
[products limit="4" columns="2"]

WooCommerce automatically creates pages like Cart and Checkout using these shortcodes. The [products] shortcode displays a grid of products with customizable attributes.

Appointment booking plugins (such as Booknetic):

[booknetic]

Adds a booking form to any page. Visitors can select a service, pick a date and time, and complete a booking directly on the page.

Each plugin documents its shortcodes in its own documentation. When you install a plugin, look for a shortcodes section in its settings or official docs to find the exact tag to use.

For shortcodes from any plugin to work, the plugin must be installed and active. If the plugin is deactivated, the shortcode has nothing to connect to and will either display as raw text or show nothing. The step-by-step guide to installing WordPress plugins walks through the full process if you need a refresher.

Common Mistakes and Misconceptions

1. Not using the Shortcode block in the block editor.
The Shortcode block is the dedicated, recommended place for shortcodes in the block editor. Whether a shortcode is processed in other block types varies depending on the plugin, theme, and WordPress version. If a shortcode appears as raw text on the front end, move it into a Shortcode block and preview again.

2. The plugin providing the shortcode is not active.
If you deactivate or delete a plugin, any shortcode from that plugin stops working. The tag remains in your content but produces no output. Before removing a plugin, check whether any of your pages use its shortcodes.

3. Extra spaces inside the brackets.
[ gallery ] is not the same as [gallery]. The extra spaces can break the shortcode. Copy the shortcode exactly as documented.

4. Smart quotes instead of straight quotes.
When you copy a shortcode from a word processor, Google Doc, or a formatted web page, the quote characters are often converted to "smart quotes" automatically: the curved left and right marks that word processing software adds. Shortcode attributes need the standard straight double quote (the simple vertical mark you get when you press the " key directly on a keyboard). Smart quotes look similar but are different characters, and WordPress will not recognize them.

To avoid this: copy shortcodes directly from the plugin's own settings page or official documentation, not from a document where text formatting was applied. If you suspect the issue is smart quotes, paste the shortcode into a plain text editor (Notepad on Windows, TextEdit in plain text mode on macOS) first, then copy and paste it from there into WordPress.

5. Missing a required attribute.
Some shortcodes need specific attributes to work. [contact-form-7] without an id attribute will not know which form to display. Check the plugin documentation for required vs. optional attributes.

6. Using an outdated shortcode.
Plugins sometimes change shortcode names between versions. If you are following old documentation or using a shortcode from an earlier version, it may no longer be recognized. Check the plugin's current documentation for the correct format.

7. Assuming shortcodes work everywhere.
Shortcodes are processed in posts, pages, and text widgets. They are not automatically processed in all custom fields, SEO plugin fields, or PHP template files. If a shortcode is not rendering in a specific location, that location may not pass content through WordPress's shortcode processor.

When You Should Care About This

When a plugin provides a shortcode to embed its feature.
Most form plugins, booking plugins, slider plugins, and ecommerce tools provide a shortcode to place their feature on a page. You will encounter this the first time you try to display a form or booking calendar outside the plugin's own settings screen.

When debugging a page that shows raw shortcode text.
If a page displays [contact-form-7 id="123"] instead of an actual form, the cause is almost always one of the mistakes listed above. The shortcode block issue and the deactivated plugin are the two most common culprits.

When you want to embed the same content on multiple pages.
Shortcodes let you place the same dynamic content in many locations without duplicating it. This is especially useful for booking forms, newsletter sign-up forms, and product listings.

When switching from the classic editor to the block editor.
If you migrated from an older WordPress setup, your existing content may contain shortcodes that worked before but now display as text in the block editor. Converting them to Shortcode blocks fixes the problem.

When evaluating whether shortcodes are right for your workflow.
If you find yourself pasting the same shortcode into many pages for layout purposes (columns, dividers, custom designs), consider whether a page builder plugin would suit you better. Visual page builders handle complex layouts through drag-and-drop blocks, which can be easier to manage than shortcodes for design-heavy work. The best WordPress page builder plugins guide covers the main options if you want to compare them.

Related Next Steps

• Find your plugin's shortcode. Open your plugin's settings page and look for a shortcodes section, or search the plugin's official documentation for "shortcode." Most plugins list the exact tag and available attributes there.
• Use the Shortcode block in the block editor. If a shortcode is not rendering, confirm you placed it inside a Shortcode block, not a Paragraph block.
• Check that the plugin is active. Go to Plugins > Installed Plugins in the WordPress admin and confirm the plugin that provides the shortcode is installed and active.
• Copy shortcodes exactly. Avoid retyping shortcodes by hand. Copy them directly from the plugin's documentation or settings screen to prevent syntax errors.
• Explore the block editor's native blocks. For many common tasks (galleries, video embeds, audio players), the block editor already has a dedicated block that does not require a shortcode. Browsing the available blocks in the block editor is worth a few minutes if you want to keep your content clean and future-proof.