Guide to WordPress Shortcodes

What are WordPress shortcodes

Shortcodes are special tags in square brackets that the WordPress engine automatically replaces with dynamic content. For example [gallery] displays an image gallery, [video] embeds video, and [contact-form] displays a contact form. Shortcodes enable users without technical knowledge to insert complex content into posts and pages by simply typing a short code.

WordPress built-in shortcodes cover basic needs, but the real power comes from the ability to create your own shortcodes. Plugin developers use them to add functionality like forms, pricing tables, sliders, and buttons, while theme developers use shortcodes for repeating design elements. Understanding the shortcodes system is an important skill for every WordPress user and developer.

Built-in WordPress shortcodes

WordPress comes with several built-in shortcodes covering basic multimedia needs. These shortcodes work out of the box without need for additional plugins and support various parameters for customizing output.

List of built-in shortcodes

• [caption] - adds a caption below the image with stylized frame
• [gallery] - displays image gallery from media library with options for columns and size
• [audio] - embeds audio player with playback controls
• [video] - embeds video player with support for MP4, WebM, and Ogg formats
• [playlist] - creates audio or video playlist from multiple files
• [embed] - embeds content from external services via oEmbed protocol

Gallery shortcode in detail

The gallery shortcode is the most commonly used built-in shortcode because it enables quickly creating image galleries. It supports parameters like ids for specific images, columns for column count, size for image size, orderby for sorting, and link for determining where image click leads. For example, [gallery ids="1,2,3" columns="3" size="medium"] displays three specific images in three columns of medium size.

Creating custom shortcodes

Creating your own shortcodes in the WordPress development environment is surprisingly simple. The add_shortcode() function is used, taking two arguments: the shortcode name and callback function that returns the HTML to display. You add this function to functions.php of your theme or to a custom plugin.

Basic structure

The callback function receives up to three parameters: $atts (array of attributes the user passes), $content (content between opening and closing tag), and $tag (name of the shortcode itself). The function must return a string with HTML and must never use echo because that would break the display order on the page. This is a common beginner mistake leading to shortcode content appearing at the top of the page instead of where the shortcode was inserted.

Simple shortcode example

Imagine you want a shortcode displaying a highlighted quote with author name. In functions.php you'd define a function taking attributes (author, color) and content (quote text) and returning stylized HTML block. The user would write in the editor [quote author="Jane Austen"]It is a truth universally acknowledged...[/quote] and WordPress would replace it with a formatted quote with author name below the text.

Shortcode parameters

Parameters (attributes) make shortcodes flexible because they enable users to customize output without changing code. Use the shortcode_atts() function to define default values and merge with values the user passed. This ensures the shortcode works even when the user doesn't specify all parameters.

Parameter types

• Text - title, color, class, ID (e.g., title="Title")
• Numeric - number of columns, result limit, width (e.g., columns="3")
• Boolean - yes/no options (e.g., show_date="true")
• List - IDs separated by comma (e.g., ids="1,5,12,7")
• Enum - predefined options (e.g., size="small|medium|large")

Always validate and sanitize parameters the user passes because shortcodes can be a vector for XSS attacks if user input is directly embedded in HTML. Use esc_attr(), esc_html(), and wp_kses() functions for output cleaning. Convert numeric parameters to int with intval() and compare boolean parameters with string true or false.

Nested shortcodes

WordPress supports nesting shortcodes, meaning you can place one shortcode inside another. This is useful for creating complex layouts where for example you have a shortcode for a row and inside it a shortcode for columns. Nested content is processed by calling the do_shortcode() function on the $content parameter within your callback function.

An important limitation is that you cannot nest the same shortcode within itself because the WordPress parser can't properly distinguish opening and closing tags. If you need such functionality, create shortcode variants with different names like [row] for row and [column] for column within row. This limitation is by design and unlikely to change in future versions.

Nesting example

A classic example is a layout shortcode where [row] creates a flex or grid container and [col width="6"] creates a column of specific width. The user can write [row][col width="4"]Left column[/col][col width="8"]Right column[/col][/row] and get a two-column layout. The row shortcode must call do_shortcode($content) so WordPress processes the nested col shortcodes before returning the final HTML.

Shortcodes in the WordPress Block editor

With the introduction of the Gutenberg Block editor, shortcodes got a dedicated block called Shortcode accepting any shortcode. However, the trend in modern WordPress development is moving toward replacing shortcodes with custom blocks providing visual preview in the editor instead of raw text in square brackets. For new projects, consider creating blocks instead of shortcodes, but for existing sites shortcodes remain completely supported and functional.

When to use shortcodes versus blocks

• Shortcodes are better for simple inserts (quote, button, icon)
• Blocks are better for complex layout elements with visual display
• Shortcodes work in Classic and Block editor
• Blocks work only in Block editor (Gutenberg)
• Shortcodes are faster to develop, blocks require JavaScript knowledge
• For plugin compatibility, shortcodes are more universal

Practical tips and best practices

Name shortcodes with the prefix of your theme or plugin to avoid conflicts with other plugins. For example, instead of [button] use [beo_button] because it's less likely another plugin uses the same name. Add documentation for each shortcode you create including parameter list, default values, and usage examples because without documentation, even you won't remember all options after a few months.

For more complex shortcodes generating significant HTML, use output buffering or template files instead of string concatenation. This makes code more readable and easier to maintain. Cache results of shortcodes requiring database queries. Use the performance check tool using Transients API because shortcodes execute on every page load and slow shortcodes can significantly slow down the site. Always test shortcodes in different contexts including widgets, excerpts, and RSS feed because behavior may differ.