To add a shortcode in WordPress, open the block editor, click Add Block and choose the Shortcode block from the Widgets section, or type /shortcode and press enter. Then type or paste your shortcode into the box. To make your own, register a handler function with add_shortcode in your theme or plugin.
What a shortcode is
A shortcode is a piece of WordPress-specific code that does a lot with very little effort. In one line, it can embed files or create objects that would otherwise need complicated code. Plugins use them all the time, and you've probably pasted one already: a contact form, a booking calendar or a product grid often arrives as a short tag in square brackets that you paste into a page.
WordPress itself has some. Put in a post or page and you get a photo gallery of the images attached to it. Shortcodes can take attributes too, like .
Adding one with the Shortcode block
- Edit the post or page in the block editor and click Add Block.
- Choose the Shortcode block from the Widgets section, or type /shortcode and press enter.
- Type or paste the shortcode, for example , into the box.
- Preview or publish the page to see the shortcode's output.
The Shortcode block itself has no settings: nothing in the block toolbar, nothing in the sidebar and no advanced settings. If you need spacing, colour or layout around it, transform the block into a group or columns block and style that. Under More options you can copy or duplicate the block, or edit it as HTML.
Why your shortcode shows up as plain text
WordPress Developer Resources make a point that explains most broken shortcodes. A shortcode only works if a plugin or theme has registered it. Type an unregistered one, or keep a plugin's shortcode after deactivating the plugin, and WordPress simply prints the text in brackets on your page. If a page suddenly shows [contact-form] instead of a form, check that the plugin is still active.
Creating your own shortcode
The Shortcode API, introduced in WordPress 2.5, handles the parsing for you and supports both self-closing shortcodes, like , and enclosing ones that wrap content. You register a shortcode with add_shortcode, which takes the shortcode name and the name of the callback function that produces the output.
| Piece | What it does |
|---|---|
| add_shortcode('name', 'callback') | Registers the shortcode and the function that runs it |
| atts | The attributes someone typed in the shortcode |
| content | Anything between opening and closing tags, for enclosing shortcodes |
| tag | The shortcode's name |
| shortcode_atts | Sets default values for attributes |
You'll put this PHP in a plugin or in your theme. A small custom plugin is usually the safer home, because a shortcode in a theme disappears if you change themes.
Rules that save debugging time
- Use all lowercase letters for shortcode names. Numbers and underscores work, but hyphens are best avoided.
- Return the output from your handler rather than echoing it. A shortcode handler works like a filter.
- Set sensible defaults with shortcode_atts, so the shortcode still works when someone leaves an attribute out.
The echo mistake's a classic, and it's easy to spot: the output appears at the top of the page instead of where the shortcode sits. Returning it puts it in the right place.
Alternatives to shortcodes
If you're repeating the same content in several places, WordPress's Synced Patterns, formerly Reusable blocks, may suit you better. A synced pattern reflects any change everywhere it's used, with no code at all. If you build pages with Elementor, its Shortcode widget lets you embed custom shortcodes into pages or posts. For more on building pages in WordPress, see whether you can create landing pages in WordPress.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
My advice for small business sites
Use the Shortcode block for the plugins you already rely on, and keep a short note of which plugin each shortcode belongs to, so a plain-text bracket never surprises you after an update. If you write your own, keep it in a small plugin, name it in lowercase and return the output. And when you're choosing plugins in the first place, my list of top WordPress plugins is a good place to start.
Want your tool on this list? Featured spots and reviews here are paid partnerships. Here's how to partner with me.
Frequently asked questions
How do I add a shortcode in the block editor?
Add a Shortcode block from the Widgets section, or type /shortcode and press enter, then paste the shortcode.
Can shortcodes have attributes?
Yes, for example .
How do I create my own shortcode?
Register a handler with add_shortcode in a theme or plugin.
Are there settings on the Shortcode block?
No. It has no specific settings in the toolbar or sidebar.
What can I use instead?
Synced Patterns for reusable content, or Elementor's Shortcode widget if you use Elementor.
