The Complete Guide to WordPress Shortcodes

Prior to the WordPress block editor, WordPress shortcodes were one of the best things to hit the WordPress editor to make it easier to add plugin and theme functions to pages, posts and other sections of a WordPress website. 

With the move to the block editor, what does this mean for most of the older plugins and websites that are still full of shortcodes? Will WordPress shortcodes still work? Is there a way to easily move from using WordPress shortcodes to WordPress blocks? 

Let’s find out. In this guide, we’ll explore WordPress shortcodes in the era of the WordPress block editor.

What Are WordPress Shortcodes?

A WordPress shortcode is a reusable, dynamic bit of code wrapped in [brackets]. Shortcodes allow you to easily insert specific functions of WordPress itself or of a plugin or theme into any post, page, custom post type or widget. Think of WordPress shortcodes like “shortcuts” or like macros on your website.

You can use WordPress shortcodes to display static content that is too tedious to keep coding and repeating. And you can also use shortcodes to display dynamic content, such as image galleries, audio players for podcasts, event calendars or changing statistics for certain data.

Shortcode Format

When it comes to inserting shortcodes, the basic [brackets] format can be “extended” in several ways, allowing you to customize or add additional settings information called attributes. Additionally, shortcuts can wrap text (or HTML) or even be nested within another shortcode.

For example, a shortcode can have the following formats:

[shortcode]

[shortcode]Some text[/shortcode]

[shortcode]<a href="http://mysite.com/">HTML content</a>[/shortcode]

[shortcode]Some text [another-shotcode] more text [/shortcode]

[shortcode icon="icon: star" background="#eeeeee" color="#F73F43" text_color="#F73F43" size="32" shape_size="16" radius="256" text_size="16" url="#" target="self" margin="0"] This is a custom icon [/shortcode]

Shortcode Attributes

Shortcodes are also flexible because they can be extended with attributes. With attributes, shortcodes offer additional customization simply by adding extra code snippets within the shortcode.

Plugins and themes offer extra guides and rubrics to help users use the correct shortcode snippets to add or remove certain elements in the output.

Here are a few examples of shortcodes with attributes.

[recent-posts posts="5"]

[recent-posts posts="5"]Posts Heading[/recent-posts]

Built-in WordPress Shortcodes

WordPress comes with several built-in shortcodes for rendering certain types of content.

The audio shortcode allows you to embed audio files and play them back.

Primarily used with individual images, the caption shortcode allows you to wrap captions around content.

The gallery shortcode allows you to add one or more image galleries to your posts and pages.

The embed shortcode allows you to wrap embedded items with a maximum (but not fixed) width and height.

The playlist shortcode implements the functionality of displaying a collection of WordPress audio or video files in a post.

The video shortcode allows you to embed video files and play them back.

Plugin & Theme Shortcodes

Specific WordPress themes and plugins have shortcodes right out of the box that you can insert in the post or page editor and will render the result on the front end. To this date, a lot of themes and plugins are still using shortcodes.

For example, shortcodes are often used in common plugins for calendars, forms, tables, memberships, countdown timers or pull quotes. Even shortcode plugins exist that allow you to create shortcodes for anything.

WordPress themes can also utilize shortcodes to render certain dynamic content that is pre-styled or provided by the them.

Custom Shortcodes

Most expert developers opt to create their own shortcodes, essentially cutting down the time it takes to code something that’s repetitive. All it takes is a simple additional file on your file directory to create the custom-shortcodes.php file. If you want to learn the ropes of custom shortcodes, here’s a guide on creating custom shortcodes.

The WordPress Shortcode API

For developers creating their own custom shortcodes, the WordPress Shortcode API provides a simple set of functions for creating WordPress shortcodes for use in posts and pages.

The Shortcode API helps plugin developers create dynamic content that users can add to pages or posts by adding the corresponding shortcode into the content area. Thankfully, the API handles all the complicated parsing, eliminating the need for writing a custom regular expression for each shortcode. In addition, helper functions are included for setting and fetching default shortcode attributes.

Developers can out the WordPress Shortcode API documentation to learn more about:

• Handling attributes
• Output
• Enclosing vs self-closing shortcodes
• Function reference
• Limitations
• Formal syntax

Shortcodes in the Classic Editor

In the past, shortcodes were inserted into the classic editor of any post or page, like this:

What Are WordPress Blocks?

Shortcodes were first … but then came block-based editing. With the introduction of WordPress 5.0 came the implementation of the long-planned Gutenberg editor or WordPress Block Editor as the main page and post editor for WordPress, replacing the classic WordPress text-based editor that’s been around for years. 

Here’s a look at the content editor prior to WordPress 5.5 (ah, those were the days!)

The Gutenberg editor was first announced on prior versions of WordPress but remained optional until WordPress 5.0 when it became the default editor. 

There’s nothing inherently wrong with the new blocked editor. In fact, most users like the improved and cleaner, less intimidating, look of the back end of WordPress. 

But with the WordPress block editor came WordPress blocks. Gone are the formatting options at the top that are reminiscent of word processing applications like Microsoft Word. Instead, formatting options have been replaced with the tabbed right sidebar options for each block. 

WordPress blocks are essentially content containers. There are many different blocks for different types of content—images, videos, texts, headings, galleries—you name it. 

There’s even a WordPress block for formatting, spacer, and divider, and they are casually arranged in categories for easy access. 

All the options and controls that were at the top now reside at the right side of the page/post editor, with tabs at the top indicating if you want to see the options for the current block alone or the whole document. 

The block editor is easier and faster and more user friendly. In addition, theme and plugin developers are also making their own blocks that add more block options to the default WordPress blocks.

Reusable Blocks vs. Shortcodes

The old way to save a set of predefined output in the WordPress classic editor was through creating your own shortcodes. Now, this method has been replaced with reusable blocks.

The ability to save predefined and pre-customized blocks has also made it easier to save the layout and design of a certain block and use it on another. Much like a page template. 

For example, if you add a button block and style it with a certain color, hover effects, etc., you wouldn’t want to keep doing that on each and every page you add that button to. If you change it to a reusable block, the button is saved on your WordPress site and becomes its own block that you can use on other pages or posts. 

You can also further update these blocks by converting them to regular blocks, saving it as a new one (with a new name), or update the existing design of the block.

Group Blocks

In WordPress 5.3 also came the introduction of group blocks and templates. 

Essentially, you are given the ability to group certain blocks together and move or update them all together. This eventually gave rise to block patterns. Block patterns have made editing content easier since users would much rather choose a pattern, and update the content rather than starting from a blank canvas. 

Block Styling Options

With each theme comes different style options. And normally the style of the content that you add on each site is predetermined by your theme. 

With the block editor, you have the option to update the style of each block individually, either to stand out, or to make them more noticeable. 

Blocks & Full Site Editing

With all these advancements and changes in the way we create and build pages on WordPress comes the idea and eventual transition to what’s called Full Site Editing. 

In the paste, most users could only update the actual body of a post or page. Certain aspects of the website, such as the header, footer, sidebars, and widgets, still largely depend on the theme. This of course made looking for the perfect theme with the right amount of options the ultimate struggle for developers and users of WordPress. 

With Full Site Editing and the introduction of the Block Builder, the trend is ticking towards making all sections of a page or post editable, in a way, using blocks. 

For example, the latest Twenty-Twenty WordPress theme follows this pattern, giving creators and website owners greater control over their website and how they would want it to look. 

Looking forward, plugin and theme developers will need to adopt a different approach when developing their software to adapt to the new full site editing and page-building experience of the WordPress block editor.  While the full application of this is still on the horizon, it’s a positive change that we’d likely see sooner rather than later.

The New Shortcode Block

Prior to the block editor, shortcodes were inserted directly into the page or page editor. Now, the WordPress block editor includes a new shortcode block.

The shortcode block makes it easy to continue to use legacy shortcodes within a post or page and maintains the integrity of the shortcode output.

The shortcode block can be added to a page or post by clicking on the Add Block button. Alternatively, you can type /shortcode and press enter.

You’ll notice that unlike other common blocks, the shortcode block does not include any specific settings in the block toolbar or editor sidebar, likely due to the fact that shortcodes can be customized using their attributes.

What Does The Block Editor Mean for WordPress Shortcodes?

The WordPress block editor has major implications for shortcodes. Let’s cover a few of the most important things to note about WordPress shortcodes in the era of the block editor.

1. The WordPress block editor fundamentally changes the need and purpose of shortcodes for most plugin and themes. With a block-based editing system, each “element” on the page has it’s own block, rather than being contained in one editable WYSIWYG editor.

Because the block editor is a totally different approach to composing a post or page, the more dynamic parts of a page that are generated by shortcodes can exist as blocks that can be added individually.

2. Blocks can now take the place of most shortcodes, removing the need for users to learn how to use shortcodes. The concept and format of shortcodes may have a steep learning curve for some users, so the block approach may be easier.

For example, take the Gravity Forms plugin. Prior to the block editor, the process for inserting a form into a post or page was different. From the classic editor, you had to use a button to insert a form into your content.

After selecting your form, the form shortcode was added to your content. Depending on the options you selected, the shortcode contained the attributes for title and description.

Now, the Gravity Forms plugin offers a forms block embed block. From the block editor, select the Forms block.

Once you’ve selected the form, you’ll actually see a better preview of how the form will look on your page. Form settings can be found in the block settings.

3. Theme and plugin developers will need to decide on the future of their shortcode implementations and converting their shortcodes to blocks. As mentioned above, hundreds of themes, plugins, and developers still use shortcodes on their websites and applications. Block adoption may be slow, but as users become more familiar with the new block editor, users are likely to request a block option.

To those developers who are still miles away from adopting the WordPress block editing system, the Full Site Editing concept can go hand in hand with their shortcodes. Plugins like review and rating plugins, audio players, date tickers, galleries, contact forms, and most anything else who still use shortcodes are still “in the game.”

4. Shortcodes aren’t going away anytime soon. That’s probably why the WordPress block editor offers the shortcode block to help maintain shortcode usage. Because shortcodes had such wide usage and implementation prior to WordPress 5.0 and the block editor, it’s important that future versions of WordPress still support shortcodes.

 5. Shortcodes can be converted to a block. Have a favorite theme or plugin that uses shortcodes? It’s likely that those shortcodes will be converted to a block at some point. If you’re a developer of a plugin or theme, or you build WordPress websites and used shortcodes in a custom theme, it is possible to rethink shortcodes as blocks.

In the next section, we’ll briefly cover how to convert WordPress shortcodes to WordPress blocks.

How to Convert WordPress ShortCodes to WordPress Blocks

Just as you can add custom shortcodes and reusable blocks, you can also easily convert custom WordPress shortcodes to WordPress blocks. 

Follow the first steps from this custom shortcode guide.

Take this basic example from Caldera Forms:

 <?php
/**
 * Handler for [cl_post_title] shortcode
 *
 * @param $atts
 *
 * @return string
 */
function caldera_learn_basic_blocks_post_title_shortcode_handler($atts)
{
	$atts = shortcode_atts([
		'id' => 0,
		'heading' => 'h3',
	], $atts, 'cl_post_title');

	return caldera_learn_basic_blocks_post_title($atts[ 'id' ], $atts[ 'heading' ]);
}

/**
 * Output the post title wrapped in a heading
 *
 * @param int $post_id The post ID
 * @param string $heading Allows : h2,h3,h4 only
 *
 * @return string
 */
function caldera_learn_basic_blocks_post_title($post_id, $heading)
{
	if (!in_array($heading, ['h2', 'h3', 'h4'])) {
		$heading = 'h2';
	}
	$title = get_the_title(absint($post_id));
	return "<$heading>$title</$heading>";
}

/**
 * Register Shortcode
 */
add_shortcode('cl_post_title', 'caldera_learn_basic_blocks_post_title_shortcode_handler');

This code takes the post ID and a heading level (h2, h3, he) and outputs the post’s title wrapped in the HTML for the heading. 

Once that’s done and you’ve tested that the code is working, you then have to register the shortcode as a block. Here’s the Step By Step Guide To Converting A WordPress Shortcode To A Gutenberg Block as an example.

More Resources on Creating WordPress Blocks

There are numerous plugins and resources available online that would help you get to that step, including the official documentation from WordPress on Writing Your First Block Type. You can check out Igor Benic’s post as well on how to create a block for displaying posts. 

After reading these guides, you’ll be able to figure out how to create your own WordPress blocks using your custom shortcodes. 

The Verdict for WordPress Shortcodes

WordPress shortcodes are and will still be one of the most important parts of WordPress. Shortcodes have helped many plugin developers make their plugins more user-friendly and a lot of theme developers extend the functionalities of their themes. Shortcodes have also reduced the number of headaches a lot of content creators and website owners have after creating their custom shortcodes when it comes to repeatedly adding and updating things that they want. 

With that said, there’s no doubt that the block editor is the future of the WordPress editing experience, so expect to see more developers contribute to making it better and even more, feature-filled, including those who are still using shortcodes. Looking ahead, we expect that more developers will transition to using and adding WordPress blocks instead of WordPress shortcodes. 

We hope you’ve learned a lot about the importance of WordPress shortcodes, what they’re for and when to use them. Hopefully, you may start creating your own custom shortcodes and eventually your own blocks, both of which are surely not going away anytime soon.