How to Use WordPress Shortcodes (With Examples)
Paste the shortcode, brackets included, into a Shortcode block: click the + inserter in the post or page, search Shortcode, drop the block in, and publish. WordPress swaps the bracketed tag for the real output — a gallery, a form, an audio player — wherever the tag sits.
knowledge
- Read time
- 4 min
- Sections
- 7
- Updated
- 14 Nov 2026
- Written by
- WebJi® team
Last editorial update: 14 November 2026.
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.
Themes and plugins have different responsibilities; a shortcode can stop rendering when the component registering it is disabled or replaced.
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 provides the hosting environment; confirm staging availability before relying on it.
Built-in shortcodes — gallery, audio, video, embed
WordPress provides six commonly used media shortcodes; their output still depends on valid attributes, content and the site configuration. They cover most media jobs:
| Shortcode | What it outputs | Example |
|---|---|---|
| [gallery] | Image grid from the media library | [gallery ids="12,34,56" columns="3"] |
| [audio] | Inline audio player | [audio src="https://example.com/track.mp3"] |
| [video] | Inline video player | [video src="https://example.com/clip.mp4"] |
| [playlist] | Playable audio or video playlist | [playlist ids="20,21" type="audio"] |
| [embed] | Auto-embed with set dimensions | [embed width="600"]video URL[/embed] |
| [caption] | Captioned image or element | [caption width="300"]Caption text[/caption] |
Everything else comes from plugins: a contact form plugin may register its own documented 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:
- Click the + inserter, search for Shortcode, and add the block — or type /shortcode and press Enter.
- Paste the tag, brackets and attributes included, exactly as the plugin documents.
- Preview — some shortcodes render live in the editor; the rest only on the published page.
- 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
Register a unique shortcode tag with add_shortcode and a callback that returns the replacement content. Keep site functionality in a maintained plugin or an approved snippets tool rather than depending on a theme that may be changed.
- Write a function that returns the output string — return, never echo, or the content lands in the wrong part of the page.
- 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.
- 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.
The add_shortcode API reference documents callback arguments and naming collisions. Validate attributes and escape output for its HTML context instead of inserting arbitrary user-controlled text into markup.
Shortcode vs block — the way forward
| Characteristic | Shortcode | Block |
|---|---|---|
| In the editor | Raw bracketed text | Visual preview while editing |
| Where it runs | Posts, widgets, templates, page builders | Block-editor content areas |
| Best for | Plugin tags pasted quickly; the same element reused across many pages | One-off elements you want to see and adjust visually |
When a plugin offers both, take the block for a single placement and keep the shortcode for reuse across dozens of pages. Performance depends on the implementation and generated output, not merely whether the interface is a shortcode or block.
Frequently asked questions
What is a shortcode in WordPress?
A bracketed tag WordPress replaces with real output at render time — [gallery] becomes a photo grid, [contact-form] becomes a form. The tag maps to a handler function, and that function's return value lands where the tag sat.
How do I use shortcodes in WordPress?
Paste the tag, brackets included, wherever the output should appear — in a post, the Shortcode block in a widget, or a theme template via do_shortcode. WordPress swaps it for the handler's output when the page renders.
How do I add a shortcode in the block editor?
Click the + inserter, search for Shortcode, add the block, paste the tag with its attributes, then save. Some shortcodes preview live; the rest render only on the published page.
Why is my shortcode showing as plain text?
The providing plugin is inactive, the tag is misspelled, the attributes use smart quotes instead of straight ones, or a custom registration never ran. Reactivate the plugin, check the tag character by character, and re-paste with straight quotes.
How do I create a custom shortcode?
Write a function that returns the output, register it with add_shortcode('tag', 'function'), and hook the registration to init. Keep the tag lowercase and prefixed so it cannot collide with a plugin, and put the code in a snippet plugin rather than functions.php.
Last editorial update: 14 November 2026.
Ready to get started with WebJi®?
Join 12,000+ businesses across India and overseas. INR pricing, 18% GST shown before payment and 24/7 email support in Hindi and English — average first reply under 60 minutes.