How to Use WordPress Shortcodes (With Examples)

Shortcodes still run half the WordPress plugin world — contact forms, galleries, booking widgets — so knowing where to paste a tag and why it sometimes shows as plain text is a working skill. The sections below cover the built-in shortcodes, the block editor route, widgets and templates, fixes for the plain-text failure, and how to register a tag of your own.

Shortcodes defined — bracket macros

A shortcode is a bracketed tag WordPress replaces with real output when the page renders: [gallery] becomes a photo grid, [contact-form] becomes the plugin's form. Behind the scenes the tag maps to a handler function, and whatever that function returns lands exactly where the tag sat.

Four things worth knowing before you paste one:

• Syntax — a tag plus optional attributes: [gallery ids="12,34" columns="3"].
• Two shapes — self-closing tags that stand alone, and enclosing tags like [caption]Text[/caption] that wrap content.
• Sources — WordPress core, themes and plugins register them; thousands of plugins ship at least one.
• Where they run — posts, pages, the Shortcode block in widgets, and theme templates through PHP.

The Gutenberg blocks guide covers the block alternative, and WordPress hosting with staging makes testing new tags safe.

Built-in shortcodes — gallery, audio, video, embed

Core WordPress ships six shortcodes that work on any theme with no plugin. They cover most media jobs:

Everything else comes from plugins: a contact form plugin registers its own tag, a booking plugin theirs. The plugin's documentation names the tag and its attributes — paste them exactly.

Using shortcodes in Gutenberg — the Shortcode block

In the block editor, four steps place any shortcode:

1. Click the + inserter, search for Shortcode, and add the block — or type /shortcode and press Enter.
2. Paste the tag, brackets and attributes included, exactly as the plugin documents.
3. Preview — some shortcodes render live in the editor; the rest only on the published page.
4. Save and check the front end before using the tag site-wide.

The Shortcode block shows raw bracketed text while you edit; that is normal. What you are checking in the preview is the rendered output, not the tag itself.

Shortcodes in widgets, PHP and custom HTML

Sidebars take the same route: open Appearance → Widgets, add the Shortcode widget block, and paste the tag. Classic Text widgets run shortcodes too, so old sidebars keep working without changes.

Theme templates need PHP: echo do_shortcode('[your_tag]') prints the output wherever the call sits, after you back up the file. Block themes skip the PHP entirely — open the Site Editor, pick the template, and drop a Shortcode block in like any other block.

When shortcodes render as text — causes and fixes

A tag that prints as literal bracketed text means WordPress found no handler for it. Work down this list — each check takes a minute:

• Plugin deactivated or deleted — reactivate it; the tag stops existing without its handler.
• Tag typo — names match exactly; a capital letter or missing underscore breaks the pairing.
• Smart quotes — attributes need straight quotes; a word processor's curly ones break parsing.
• Custom tag never registered — the add_shortcode call is missing, misspelled or hooked after content renders.
• Context that skips shortcodes — excerpts and custom HTML areas may need an explicit do_shortcode call.

Test the fix on staging and change one thing at a time, so you know which change restored the output.

Creating your own shortcode with add_shortcode

1. Write a function that returns the output string — return, never echo, or the content lands in the wrong part of the page.
2. Register it with add_shortcode('your_tag', 'your_function'), keeping the tag lowercase and unique — prefix it with your site or plugin name so it cannot collide with another plugin's tag.
3. Hook the registration to the WordPress init action so the tag exists before any content renders.

The safest home for that code is a code-snippets plugin or a small custom plugin, not your theme's functions.php — switching themes removes shortcodes defined there. When you need options such as a post count or a colour, let the function read attributes through shortcode_atts with defaults, so the tag still works when a parameter is missing.

Shortcode vs block — the way forward

When a plugin offers both, take the block for a single placement and keep the shortcode for reuse across dozens of pages. There is no speed difference between the two.