A shortcode is a small piece of text, wrapped in square brackets, that WordPress replaces with dynamically generated content or functionality when a page is rendered. Instead of embedding complex HTML or PHP code directly into content, a shortcode provides a simple placeholder — like [contact-form] or — that triggers WordPress to output whatever content or interface the shortcode is programmed to display.

Shortcodes were introduced in WordPress 2.5 and became the primary mechanism for inserting dynamic functionality into the Classic Editor. They’re still widely used today, particularly by plugins that need to embed forms, galleries, sliders, maps, and other interactive elements into post or page content. While the block editor has taken over many use cases that shortcodes once served, shortcodes remain an active part of the WordPress ecosystem — and understanding them is useful for anyone managing a WordPress site.

How Shortcodes Work

The mechanics:

  1. A developer (or plugin) registers a shortcode using WordPress’s add_shortcode() function, associating a tag name with a PHP callback function.
  2. When a page containing that shortcode is loaded, WordPress scans the content for shortcode tags and passes any attributes to the callback function.
  3. The callback function returns HTML output, which WordPress inserts in place of the shortcode.

Shortcodes can be self-closing () or enclosing ([box]content here[/box]). They can also accept attributes — key-value pairs that modify their behavior: .

In the block editor (Gutenberg), shortcodes are used through the dedicated Shortcode block. In the Classic Editor and in text widgets, they can be typed directly into the content field. Most plugins that rely on shortcodes also provide blocks for the modern editor, but shortcode support is maintained for backward compatibility.

// Example: Registering a simple shortcode in functions.php
add_shortcode( 'hello_world', function( $atts ) {
    $atts = shortcode_atts( array(
        'name' => 'World',
    ), $atts );
    return '<p>Hello, ' . esc_html( $atts['name'] ) . '!</p>';
});
// Usage: [hello_world] outputs: <p>Hello, World!</p>
// Usage: [hello_world name="Ron"] outputs: <p>Hello, Ron!</p>

Purpose & Benefits

1. Insert Dynamic Functionality Without Writing Code

For site owners without development experience, shortcodes provide a way to embed plugin-powered features — contact forms, event calendars, testimonial carousels, pricing tables — by typing or pasting a simple tag rather than editing templates or adding custom code. Many plugins document their shortcodes clearly so non-developers can use them confidently.

2. Embed Reusable Content Across Multiple Pages

Shortcodes can be registered to output content that appears in multiple places across a site. Update the underlying function, and every instance of the shortcode updates automatically. This is useful for content like pricing tables, call-to-action blocks, or promotional banners that appear on multiple pages and need to stay consistent.

3. Bridge Classic and Modern WordPress Workflows

For sites built with the Classic Editor — or for clients who haven’t migrated to block-based editing — shortcodes remain the standard mechanism for embedding dynamic content. They also provide backward compatibility for older plugin functionality as the ecosystem transitions to blocks. Understanding shortcodes is useful context when working with PHP in WordPress themes and plugins.

Examples

1. Contact Form Plugin Shortcode

A plugin like Contact Form 7 or Gravity Forms generates a shortcode for each form created: [contact-form-7 id="42" title="Contact Form"]. Pasting this shortcode into any page or post embeds the complete contact form at that location. The plugin handles all the form rendering, validation, and submission — the shortcode is just the insertion point.

2. WooCommerce Shortcode for Product Display

WooCommerce includes built-in shortcodes for displaying products outside the standard shop pages. [products limit="4" orderby="popularity"] outputs four of the store’s most popular products, complete with images, prices, and “Add to Cart” buttons. A marketing team can embed this on a landing page without developer involvement.

3. Custom Shortcode for Reusable Content

A developer registers a custom shortcode [company-cta] in functions.php that outputs a styled call-to-action block with the company’s current phone number and a button. This shortcode is placed on 20 different pages. When the phone number changes, the developer updates it in one place — the shortcode function — and all 20 pages update automatically.

Common Mistakes to Avoid

  • Nesting shortcodes that don’t support nesting — WordPress doesn’t support multiple levels of nesting for the same shortcode by default. Some shortcodes support nesting through explicit design; most don’t. Check plugin documentation before attempting to nest shortcodes.
  • Using shortcodes in PHP template files — In template files, shortcodes need to be processed with do_shortcode() rather than typed directly. Writing echo '' outputs the literal text; echo do_shortcode('') outputs the rendered content.
  • Keeping shortcodes from deactivated plugins — When a plugin is deactivated or removed, its shortcodes stop working and output [shortcode-name] as visible text — or nothing at all. Audit your content for orphaned shortcodes when removing plugins.
  • Relying on shortcodes for layout that should be in blocks — The block editor handles most layout and content composition tasks that shortcodes used to manage. Using a shortcode where a native block would work better leads to a less maintainable site over time.

Best Practices

1. Use the Block Editor’s Shortcode Block for Modern Sites

In Gutenberg, insert the dedicated Shortcode block rather than placing shortcodes in paragraph or HTML blocks. The Shortcode block renders correctly in the editor (showing either the rendered output or the shortcode tag, depending on the plugin) and is the intended mechanism for using shortcodes in the modern WordPress editing experience.

2. Document Custom Shortcodes for Non-Developer Users

If you or a developer registers custom shortcodes for a client site, document them clearly: what the shortcode does, what attributes it accepts, and example usage. Shortcodes are only useful if the people managing the site know they exist and understand how to use them. A simple internal document or a note in the site’s documentation prevents confusion later.

3. Evaluate Block Alternatives Before Adding New Shortcodes

Before building a new shortcode for functionality that needs to be inserted into content, check whether a native WordPress block or a block-based plugin feature already handles the use case. Blocks are the future of WordPress content composition — shortcodes should be used when blocks aren’t available or when backward compatibility with older content is required.

Frequently Asked Questions

Are shortcodes still relevant with the block editor?

Yes, but their role has narrowed. The block editor replaces most of what shortcodes used to do for layout and content composition. However, shortcodes remain relevant for plugin-powered functionality (forms, e-commerce widgets, membership content), legacy content on sites built before the block editor era, and custom developer tools. They aren’t going away, but new development should favor blocks when possible.

Can I create my own shortcodes?

Yes. Any developer with access to your functions.php file or a custom plugin can register shortcodes using WordPress’s add_shortcode() function. This is a standard part of WordPress development and doesn’t require core file modifications. Custom shortcodes are a straightforward way to add reusable functionality to any WordPress site.

Why does my shortcode appear as text instead of rendering?

Several causes: the plugin that registered the shortcode is deactivated or deleted, the shortcode is in a location where it’s not processed (some theme areas don’t run content through WordPress’s shortcode parser), or the shortcode tag is misspelled. Check that the relevant plugin is active and that the shortcode is placed in content fields that support it.

Do shortcodes affect page speed?

It depends on what the shortcode outputs. A simple shortcode that outputs a small HTML snippet has negligible performance impact. A shortcode that triggers external API calls, loads large scripts, or runs complex database queries can add meaningful load time. Evaluate each shortcode’s implementation when diagnosing PageSpeed issues.

What’s the difference between a shortcode and a widget?

Shortcodes are text placeholders embedded in post/page content. Widgets are interface components assigned to specific areas of the theme (sidebars, footers) through the WordPress Widgets interface. Some plugins offer both a shortcode and a widget for the same functionality — use the shortcode to place content in page content areas, and the widget for theme sidebar/footer areas.

Related Glossary Terms

How CyberOptik Can Help

As a WordPress-focused agency, we work with shortcodes on every project — from migrating legacy shortcode-heavy sites to the block editor, to building custom shortcodes that give clients exactly the functionality they need. Whether you need custom development, a site audit, or help troubleshooting shortcode rendering issues, our developers can help. Get in touch to discuss your project or explore our WordPress development services.