How to Use Shortcodes in WordPress: Complete Guide

A shortcode is a small tag in square brackets — like [contact-form] or — that WordPress expands into content or HTML when a page renders. Shortcodes let you drop complex functionality into posts, pages, or templates without writing code each time. This guide covers every context where you can use shortcodes, how to pass attributes, how to build your own, and how shortcodes fit into WordPress in 2026 alongside the block editor.

Shortcode Formats

There are three formats a shortcode can take:

• Self-closing: [shortcode_name] — the most common. No wrapping content required.
• With attributes: [shortcode_name attribute="value" another="123"] — passes parameters to control the output.
• Enclosing: [shortcode_name]Content goes here[/shortcode_name] — the shortcode wraps and processes the content between the tags.

Plugins that provide shortcodes document which format they use and what attributes they accept. Common examples: WooCommerce uses [products] with category/tag attributes; contact form plugins output their forms via [contact-form-7 id="123"]; gallery functionality via .

Using Shortcodes in the Block Editor

The block editor (Gutenberg) has a dedicated Shortcode block for this purpose. To add one:

1. Click the + button to add a new block (or type / on a new line)
2. Search for Shortcode and select the Shortcode block
3. Paste your shortcode into the field — including the square brackets
4. The block displays the shortcode text in the editor, but renders the output on the front end when the page is published or previewed

You won’t see the shortcode output live in the editor — the Shortcode block is one of the few in WordPress that requires a preview or front-end view to see the rendered result. Click Preview (top right) to check the output before publishing.

Shortcodes inside paragraph blocks don’t work. If you type a shortcode directly into a Paragraph block, WordPress will render it as literal text. Always use the dedicated Shortcode block. The block editor expects shortcodes to be in their own block, not mixed into text content.

Using Shortcodes in the Classic Editor

In the TinyMCE classic editor, shortcodes work directly in the content area in both Visual and Text mode. Type or paste the shortcode anywhere in the post body — WordPress processes it automatically when the post renders.

In Visual mode, the shortcode will appear as the bracketed text. In Text (HTML) mode, you can see and edit it alongside HTML. Either mode works — the rendering happens server-side when the page is served, not in the editor itself.

Classic editor shortcodes also work in the Excerpt field, though fewer plugins process shortcodes in excerpts by default. If you need a shortcode to render in an excerpt, a small functions.php snippet can add the filter.

Using Shortcodes in Page Builders

All major page builders include a dedicated element for shortcodes:

• Elementor: Add the Shortcode widget (search “Shortcode” in the widget panel). Paste your shortcode in the Enter Your Shortcode field.
• Divi: Add a Code module. Paste the shortcode inside it.
• Beaver Builder: Add an HTML module. Paste the shortcode into the HTML content field.
• WPBakery: Add a Shortcodes element, or use any text element — WPBakery processes shortcodes inside text content.

When a shortcode appears broken or renders as text in a page builder, the most common cause is the page builder encoding square brackets as HTML entities ([ / ] or [ / ]). This happens when content is pasted into a rich text field rather than a code/shortcode-specific field. Use the dedicated shortcode element, not a text or heading element, to avoid this.

Using Shortcodes in Widget Areas

By default, WordPress does not process shortcodes in text widgets. To enable shortcodes in the classic Text widget:

add_filter( 'widget_text', 'do_shortcode' );

Add this to your theme’s functions.php or a site-specific plugin. After adding the filter, any shortcode in a Text widget will render its output rather than display as literal text.

If you’re using the block editor’s widget area (Widgets screen in wp-admin), use a Shortcode block there — the same as you would in a post. The filter above is only needed for the legacy Text widget.

Using Shortcodes in PHP Templates with do_shortcode()

To execute a shortcode inside a theme template file, PHP file, or anywhere outside the WordPress content pipeline, use the do_shortcode() function:

<?php echo do_shortcode( '[your_shortcode_here]' ); ?>

The function takes the shortcode string and returns the rendered HTML output. You must echo it — do_shortcode() returns a string, it doesn’t output anything on its own.

With attributes:

<?php echo do_shortcode( '' ); ?>

With a variable shortcode name or dynamic attributes:

<?php
$post_id = get_the_ID();
echo do_shortcode( '[my_shortcode post="' . intval( $post_id ) . '"]' );
?>

Note the intval() call when inserting dynamic values into shortcode attributes — this sanitises the value before it becomes part of a string. This isn’t required for static shortcodes but is good practice when the attribute value comes from a variable. For more on using PHP in WordPress templates, see how to get the title in a WordPress template page.

Shortcode Attributes

Attributes let users pass parameters to a shortcode. Plugin documentation will list available attributes and their defaults. Common pattern:

[product_showcase category="featured" limit="6" columns="3"]

When you’re building your own shortcode (see next section), you define which attributes your shortcode accepts and what their default values are. When using a plugin’s shortcode, check the plugin’s documentation — the wp-admin settings page for the plugin often lists available shortcodes and their attribute options.

Enclosing Shortcodes

Some shortcodes wrap content — the output is built around the text or HTML between opening and closing tags:

[button url="https://example.com" style="primary"]Get Started[/button]

The content between the tags (Get Started in this case) is passed to the shortcode function as a parameter. WordPress’s built-in shortcode is an enclosing shortcode — it wraps an image with a caption element. The plugin’s documentation will indicate whether a shortcode is self-closing or enclosing.

Creating a Custom Shortcode

If no plugin provides the shortcode you need, you can register your own with add_shortcode(). Add this to your theme’s functions.php or a site-specific plugin:

/**
 * Outputs the current year — useful for keeping copyright notices current.
 */
function current_year_shortcode() {
    return date( 'Y' );
}
add_shortcode( 'current_year', 'current_year_shortcode' );

After adding this, the shortcode [current_year] will output the current year wherever it’s placed.

A shortcode with attributes:

function highlight_box_shortcode( $atts, $content = null ) {
    $atts = shortcode_atts(
        array(
            'color' => 'yellow',
        ),
        $atts,
        'highlight_box'
    );

    return '<div class="highlight-' . esc_attr( $atts['color'] ) . '">'
        . do_shortcode( $content )
        . '</div>';
}
add_shortcode( 'highlight_box', 'highlight_box_shortcode' );

This registers an enclosing shortcode [highlight_box color="blue"]Content[/highlight_box] that wraps content in a styled div. Key points:

• shortcode_atts() merges provided attributes with defaults — any attribute not passed by the user gets its default value.
• Always esc_attr() attribute values before inserting them into HTML output — shortcode attributes come from post content and could contain unexpected characters.
• Call do_shortcode( $content ) on the enclosed content to allow nested shortcodes to render.
• The callback returns the HTML string — it does not echo it. WordPress handles the output.

If the functionality you need is more complex than a few lines, consider whether a custom block might be a better fit. For the comparison between shortcode-based extensions and custom code approaches, see page builders vs. custom code in WordPress.

Shortcodes vs. Blocks in 2026

Shortcodes were introduced in WordPress 2.5 (2008) as a way to embed functionality in post content without writing HTML. The block editor, introduced in WordPress 5.0 (2018), provides a visual, modular alternative to shortcodes for most of the same use cases.

Shortcodes are still fully supported and will not be removed from WordPress — too many sites depend on them. But for new functionality, blocks are the preferred pattern:

• Blocks are preferable when: you’re building new functionality, you want editors to see the output in the editor rather than a placeholder, you want drag-and-drop reordering, or you’re starting a project where you control the editor experience.
• Shortcodes are appropriate when: you’re using a plugin that provides shortcodes and hasn’t shipped a block equivalent yet, you need to output content in a PHP template via do_shortcode(), you’re working in a classic editor environment, or you need to embed functionality in locations that don’t support blocks (widget areas on older themes, certain theme option fields).

The two can coexist on the same site without conflict. Many widely-used plugins (WooCommerce, contact form plugins, membership plugins) ship both shortcodes and blocks, letting you choose the appropriate format for each context.

Troubleshooting: Shortcode Showing as Text

If a shortcode appears on the front end as literal text (like [contact-form-7 id="123"] instead of the rendered form), the usual causes are:

• The plugin that registers the shortcode is not active. WordPress only processes shortcodes that have been registered via add_shortcode(). If the plugin is deactivated, the shortcode is unknown and renders as text. Check wp-admin → Plugins and verify the relevant plugin is active.
• Wrong location in the block editor. Typing a shortcode into a Paragraph block rather than a Shortcode block will render it as text. Replace the paragraph block with a Shortcode block.
• Square brackets encoded by a page builder or editor. Some rich text editors convert [ to HTML entities. Use the dedicated shortcode element in your page builder rather than a text element.
• The shortcode tag is misspelled. Shortcode names are registered exactly — a typo (extra space, wrong underscore) means WordPress doesn’t recognise it.

For persistent issues tracing plugin interactions, see how to identify and fix WordPress plugin conflicts.