WordPress Shortcodes

Shortcodes are one of the core WordPress tools that let you add dynamic functionality to pages without directly editing theme template code. They are widely used to insert forms, galleries, post lists, and custom blocks. In this article, we’ll cover what shortcodes are in WordPress, how to use them, where to add them, and how to create your own solutions for real-world projects.

What is a shortcode in WordPress and how does it work

A shortcode in WordPress is a special text construct inside square brackets that allows you to trigger specific functionality without directly editing the theme’s code. This mechanism is built into the core system and is part of the standard API described in the official documentation on WordPress.org. Thanks to shortcodes, content editors can add complex elements using only the text editor.

For example, in page content a shortcode may look like this:

[gallery]

Or with parameters:

[contact-form-7 id="123"]

From a technical perspective, a shortcode is a link between text in the content and a PHP function. When processing a page, WordPress scans the content, finds registered shortcodes, and replaces them with the output of the corresponding function. That’s why the same shortcode can appear as a short entry in the editor but turn into a full HTML block on the front end of the site.

In the editor, the user only sees a text construct, for example:

[products limit="4"]

But on the front end, WordPress outputs ready HTML with product cards, images, prices, and buttons.

For example, when a user adds a gallery shortcode to the text, WordPress automatically generates the image markup according to the settings, without requiring manual layout work. This approach greatly simplifies working with dynamic content and makes the system flexible for both developers and content managers.

As a result, one short entry in the editor:

[gallery ids="12,15,18"]

turns into a full image gallery on the site page.

What are WordPress shortcodes used for

WordPress shortcodes are used to separate logic from content and simplify site management. Instead of editing templates every time or duplicating HTML code, you create or get a shortcode once and then use it anywhere you need. This is especially important for websites where content is regularly updated or created by different authors.

For example, the editor can use a simple entry in the page content

[contact-form]

or the dynamic block:

[latest_posts count="3"]

In practice, shortcodes are often used to display contact forms, galleries, buttons, product blocks, or post lists. For example, online stores and marketplaces use shortcodes to dynamically display product cards, while corporate websites use them for repeated sections with contact information or calls to action. A similar approach can be seen on large commercial platforms, where the same block is used across dozens of pages without manual editing.

In such cases, pages may use one universal shortcode, for example:

[product_card id="25"]

Another important reason for using shortcodes is flexibility. A developer can change the internal logic or markup of a shortcode without touching the content. As a result, the site is easier to maintain and the risk of errors during updates is significantly reduced.

To do this, it’s enough to update the shortcode code that is used, for example, in this form:

[cta_block]

and all pages where it is inserted will automatically get the updated appearance.

Where can you use shortcodes in WordPress

One of the key advantages of shortcodes is that they can be used in almost any part of a WordPress site. The most common option is inserting a shortcode directly into a page or post’s content. In this case, the editor works only with text, while the system automatically replaces the shortcode with ready HTML output when loading the page.

In addition to main content, shortcodes are often used in widgets, sidebars, the footer, or even in menus. This makes it possible to display the same elements - such as a subscription form or a contacts block - in multiple areas of the site at once. This approach is especially convenient for websites with many pages, where it’s important to maintain a consistent structure and avoid duplicating code.

Another important scenario is the use of shortcodes in the theme or plugin PHP files. With a dedicated WordPress function such as do_shortcode(), you can call a shortcode directly inside a page template, which allows you to combine content flexibility with theme logic. That’s why shortcodes are actively used both in classic themes and in modern projects that combine different approaches to building the interface.

How to add a shortcode to a WordPress post or page

Adding a shortcode to a WordPress page or post is one of the simplest ways to use this mechanism. In most cases, you just insert the shortcode where you need it in the text, and the system will automatically process it when displaying the page. This approach requires no technical knowledge and works well for everyday content work.

In the Gutenberg block editor, you can use the dedicated “Shortcode” block or insert the shortcode directly into a paragraph if the theme supports it. After saving the page, WordPress will replace the text construct with the output generated by the corresponding function or plugin. This is convenient when you need to quickly add a form, gallery, or dynamic block without configuring complex parameters.

For sites that still use the Classic Editor, the principle is the same. The shortcode is simply inserted into the text editor in either Visual or HTML view. As a result, regardless of the chosen editor, the logic of how shortcodes work remains unchanged, making them a universal tool across different WordPress versions.

How to add a shortcode in the WordPress Classic Editor

The WordPress Classic Editor is still used on many sites, especially projects built a few years ago or running on custom themes. In this environment, shortcodes remain one of the primary ways to add dynamic content without changing templates. The mechanism itself is no different from the modern block editor.

To add a shortcode, it’s enough to paste it into the editor text in Visual mode or in HTML mode. WordPress processes both correctly, but in practice developers often recommend using HTML mode, especially if the shortcode has parameters or nested content. This reduces the risk that the Visual editor will automatically change formatting.

It’s also worth noting that some older themes or plugins may include their own editor buttons for inserting shortcodes. In that case, the system actually only automates the insertion of the text structure, but the subsequent processing is still performed by standard WordPress tools/means. It is precisely thanks to this versatility that shortcodes remain compatible even with older versions of the editor.

How to add a shortcode in Gutenberg (the WordPress block editor)

The Gutenberg block editor has become the standard in WordPress, and working with shortcodes in it is very easy. The most straightforward method is to use the dedicated “Shortcode” block, designed specifically for this purpose. In this block, the shortcode is inserted as plain text, and WordPress processes it when displaying the page.

Besides the dedicated block, in many themes, shortcodes also work correctly when inserted directly into a text block. This is convenient when you need to place a dynamic element between paragraphs or inside existing content. In the visual editor, the shortcode usually appears as text, but after publishing it is automatically converted into the corresponding HTML output.

It’s important to remember that Gutenberg does not execute shortcodes in edit mode the same way it does on the front end. This means the preview may look different from the final result. This behavior is normal and does not affect correct shortcode functionality after publishing.

How to add a shortcode to a widget or WordPress sidebar

Shortcodes are often used in widgets and sidebars when you need to display a dynamic element on all pages or selected pages of the site. These can be contact forms, banners, post lists, or any custom blocks created for the project’s needs. This approach lets you manage content centrally without editing each page individually.

In modern WordPress versions, this is usually done with the “Text” widget or “Custom HTML”. These widgets can have a shortcode inserted into them just like regular content, after which WordPress will process it during site rendering. In most cases, no additional settings are required, as shortcode support in widgets is already included at the core level.

On sites with older themes, you may sometimes find that a shortcode does not execute in a widget. In such cases, the issue is usually not the shortcode itself but theme limitations. However, even in these projects the problem is typically solved with a few lines of code, which once again highlights the versatility of this mechanism.

How to add a shortcode to a WordPress menu

Using shortcodes in a WordPress menu is a less obvious but quite useful scenario. It’s used when you need to display a dynamic element directly in navigation - for example a button, an icon, a search form, or a custom block with changing data. This is often seen on commercial sites and services with non-standard menu structures.

WordPress does not natively allow shortcodes to be inserted directly as a menu item, but the problem is easily bypassed. The most common approach is to add a “Custom Link” menu item and use the shortcode in the “Label” field. If the theme supports the execution of shortcodes in the menu, WordPress will process it and output the result on the front end.

In some cases, the theme or plugin may not execute menu shortcodes by default. Then the problem is solved at the code level by explicitly enabling shortcode processing for menu items. Developers often use this approach when the menu becomes part of a more complex interface and needs to work as a functional element, not just a list of links.

How to add a shortcode to a WordPress footer or header

The site footer and header are areas that usually contain repetitive content: contact information, buttons, banners, subscription forms, or utility elements. That is why shortcodes are used quite often here, as they allow you to change the content without editing the templates every time. This approach is especially convenient for sites that are updated regularly or have multiple language versions.

The simplest way to add a shortcode to the footer or header is to use widgets, if the theme supports the respective areas. In that case, the shortcode is inserted the same way as in any other widget, and WordPress processes it automatically. This solution fits most standard themes and does not require code access.

If the header or footer is hardcoded in theme templates, the shortcode can be called directly in a PHP file. For that, WordPress provides a special function that processes the shortcode and returns the output. This approach is often used in custom themes where the site structure is controlled at the code level.

How to use a shortcode in WordPress PHP files

In addition to working with content, shortcodes are often used directly in a theme’s or plugin’s PHP files. This approach allows you to combine shortcode flexibility with full control over page templates. This is especially relevant for custom themes, where part of the content is generated programmatically and part is managed via the admin area.

For example, you can call a shortcode directly in a template file:

echo do_shortcode('[contact-form]');

To call a shortcode in PHP, WordPress uses a special function that processes the text construct the same way as in the editor. This behavior is documented in the official WordPress developer reference. As a result, the shortcode returns HTML that can be output anywhere in a template - for example in header.php, footer.php, or a specific page file. That’s why shortcodes are often used for repeatable blocks that must appear regardless of page type.

In practice, this can look like the following in header.php or footer.php:

echo do_shortcode('[cta_block]');

or in a product page template:

echo do_shortcode('[product_card id="25"]');

This approach is also convenient because a developer can change the internal logic of a shortcode without touching templates. If, for example, the structure of a product card or a data block changes, it’s enough to update the shortcode code, and all places where it’s used will automatically receive the new version.

This means that even complex blocks called with a single line:

echo do_shortcode('[latest_posts count="4"]');

can be updated centrally without editing dozens of templates.

How to find or get a shortcode in WordPress

In most cases, the shortcode already exists, and the user’s task is not to create it but to find it correctly. Most often, shortcodes come from plugins that add functionality: contact forms, galleries, sliders, product catalogs, or third-party integrations. Information about these shortcodes is usually available in the plugin settings or in its documentation.

Many popular plugins display the shortcode directly in the WordPress admin area. For example, after creating a contact form or gallery, the system immediately shows a ready shortcode that you can copy and paste into a page. This approach minimizes the risk of errors and allows working with shortcodes even without technical experience.

If you’re dealing with custom shortcodes, you should look for them in the theme or plugin code. Usually, they are registered through the standard WordPress API, so it’s easy to locate them by keywords in the code. In larger projects, it’s helpful to keep separate documentation or comments so content managers understand which shortcodes are available and what they are used for.

How to create your own shortcode in WordPress

Creating your own shortcode in WordPress lets you implement functionality that is not covered by the system’s standard features or plugins. This approach is often used in custom projects where it’s important to have full control over logic and content output. In this case, the shortcode becomes a convenient interface between code and the page editor.

At a basic level, a shortcode consists of a PHP function and its registration through the WordPress API. The function is responsible for generating the content, and the shortcode triggers that logic in the required place on the site. The code is typically placed in a custom plugin or a child theme to avoid issues when the main theme is updated.

The simplest example looks like this: WordPress registers a shortcode with a certain name, after which any post or page can use it as a short text command. This simplicity is what makes shortcodes popular even in complex projects.

A basic example of creating a shortcode in WordPress

To understand how shortcodes work, it’s enough to look at the simplest example. At this stage, what matters is not so much the shortcode’s purpose, but the logic of creating and connecting it to WordPress. This example can be used as a base for more complex solutions later.

The code below creates a shortcode that outputs simple text:

<?php
function hello_shortcode() {
  return 'Hello, WordPress!';
}
add_shortcode('hello', 'hello_shortcode');
?>

After adding this code, WordPress registers a new shortcode named hello. You can use it in any post or page:

[hello]

When the page loads, WordPress will find this shortcode in the content, run the linked PHP function, and insert the result into the final HTML. The key point is that the function returns the value using return, not direct output, which ensures the shortcode works correctly in any context.

How to pass parameters to a WordPress shortcode

Parameters in shortcodes (also called attributes) are needed so the same shortcode can be used in different scenarios without copying and rewriting code. Instead of creating a separate shortcode for each variation, the developer builds one universal shortcode, and the editor controls the result via parameters in square brackets. This is especially useful when a shortcode outputs a button, a data block, or a dynamic list.

Technically, parameters are passed as “key=value” pairs and processed in code as an array. To set default values and avoid errors, WordPress conventionally uses shortcode_atts().

Below is an example of a button shortcode that accepts text and a URL:

function button_shortcode($atts) {
$atts = shortcode_atts([
'text' => 'Press',
'url'  => '#',
], $atts);

return '<a href="' . esc_url($atts['url']) . '" class="btn">'
 . esc_html($atts['text']) .
 '</a>';
}
add_shortcode('button', 'button_shortcode');

Now you can call this shortcode with different parameters in content without changing PHP code:

[button text="Buy" url="/shop"]

In the same way, you can pass other parameters: the number of elements in a list, a category to display, a styling variant, or an operating mode. The key is to keep parameters simple and predictable so editors can use them without extra instructions.

How to create a shortcode in a WordPress plugin

Although you can add shortcodes directly into a theme file, in practice the better approach is to move them into a separate plugin. This keeps functionality independent from the theme and allows safe design updates without losing custom logic. This is how professional WordPress projects typically work.

A shortcode plugin can be extremely simple. It’s enough to create a separate PHP file in the plugins directory and register the shortcode there via the standard WordPress API. After activating the plugin, the shortcode becomes available across the whole site: in posts, pages, widgets, and templates.

This approach is often used for business logic that is not tied to visual design. For example, displaying product cards, service lists, or special blocks that should appear on different pages. In commercial projects, plugin-based shortcodes allow you to scale functionality quickly and hand the site over between teams without losing structure.

Custom WordPress shortcodes with ACF

Combining custom shortcodes with the Advanced Custom Fields (ACF) plugin is one of the most common approaches in complex WordPress projects. This setup lets you store data in the admin area in a structured way and output it in content or templates using simple text commands. This is especially convenient for sites where content changes often, but block structure should remain consistent.

In practice, ACF shortcodes are often used to output repeatable cards, lists, or sections. For example, on casinobonuszok.com ACF-based shortcodes are used to display online casino cards across different pages. In this case, all data—name, rating, bonus, link—is stored in ACF fields, while the shortcode is responsible only for building the HTML structure. A similar approach is also widely used on e-commerce and review platforms, where shortcodes output product, service, or partner-offer cards—often implemented on sites similar to major marketplaces or product catalogs.

The simplest scenario is outputting a single ACF field. For example, if a phone number or service information is stored in site settings, a shortcode lets you insert that data into any page without duplicating text. In this case, WordPress acts as a data management system, and the shortcode acts as a universal display tool.

In more complex cases, ACF shortcodes output entire blocks: lists of benefits, specification tables, ratings, or dynamic sections with buttons. That’s why this approach is often chosen by commercially oriented projects where it’s important to update data quickly without developer involvement. You can learn more about ACF features in the plugin’s official documentation or in WordPress community resources that complement the core information from the official WordPress site.

Thanks to this architecture, ACF shortcodes become not just a technical tool, but a full part of a site’s content strategy—especially for scalable, SEO-focused projects.

Dynamic shortcodes: WP_Query and working with posts

In addition to static data or ACF fields, shortcodes are often used to generate dynamic content based on WordPress posts. In such cases they work together with WP_Query, allowing you to select posts, pages, or custom post types based on given conditions. This makes shortcodes useful not only for layout but also for page-building logic.

A typical example is displaying the latest posts, news, or case studies in the middle of a page or on a landing page. Instead of manually adding links, you insert a shortcode and WordPress automatically prepares an up-to-date list. This approach is often used on blogs, corporate sites, and commercial platforms where content should update automatically without editor involvement.

In code, the shortcode runs a database query, builds HTML markup, and returns it where the shortcode is called. The important point is that after running the query you need to correctly restore the global post context to avoid conflicts with other page elements. That’s why dynamic shortcodes require a bit more attention, but they also unlock much broader options for building flexible pages.

How to edit or change a shortcode in WordPress

Editing a shortcode in WordPress usually happens at the code level, not inside the content. This is one of the key features of the mechanism: the text construct in the editor remains the same, while all logic and markup are controlled by the PHP function bound to the shortcode. That’s why changing the shortcode code automatically affects every page where it is used.

If the shortcode was added via a plugin, you edit the plugin files. If the shortcode is stored in a theme or child theme, changes are made in the functions file. Most often, edits involve HTML structure, styling, or data-fetching logic—for example when working with ACF or WP_Query. The content itself requires no changes, which greatly simplifies site maintenance.

Sometimes you need to change the shortcode syntax or its parameters. In such cases, it’s important to consider backward compatibility, especially if the shortcode is already widely used. Developers typically keep old parameters working or add default values to avoid errors on published pages.

How to remove a shortcode in WordPress

Removing a shortcode in WordPress is usually connected not only with deleting code, but also with properly handling the content where it was used. If a shortcode is no longer needed or has been replaced, it’s important to make sure its absence will not cause “broken” elements on site pages.

If the shortcode was registered by a plugin, the easiest approach is to deactivate or delete that plugin. In this case WordPress will stop recognizing the text construct. However, the shortcode will remain in the content as plain text, so before removal it’s best to replace it or remove it from the pages where it was used.

In the case of custom shortcodes added manually, it’s enough to delete or comment out the PHP code responsible for registering them. At the same time, you need to consider that old posts may still contain calls to the shortcode. In practice, teams often replace the shortcode with a new solution or static content first, and only then fully remove it from code to preserve site integrity.

Why a shortcode doesn’t work in WordPress

A situation where a shortcode doesn’t display or shows as plain text happens fairly often, especially on sites with custom themes or many plugins. In most cases, the issue is not WordPress itself but the context where the shortcode is used. For example, not all site areas automatically process shortcodes unless it’s enabled by the theme or template logic.

Another common reason is code errors or incorrect shortcode registration. If the PHP function doesn’t return a value or contains a syntax error, WordPress won’t be able to execute the shortcode correctly. These issues often occur when editing custom shortcodes or when plugins conflict due to using the same shortcode names.

Special attention should be paid to editors and page builders. Some of them have their own content processing rules, so a shortcode may work in a post but not execute in a menu or a non-standard block. In such cases, the issue is typically solved at the code level or with settings that explicitly enable shortcode processing in the required place.

Common mistakes when creating and using shortcodes

One of the most common mistakes when working with shortcodes is using the wrong approach for outputting data. A shortcode must return a result rather than output it directly, which aligns with the recommendations described in the official WordPress shortcode documentation. If direct output is used inside a PHP function, it can lead to incorrect page rendering or situations where content appears in an unexpected place. That’s why a shortcode sometimes “works” in one template but doesn’t work in another.

Another typical issue is missing checks before outputting data. This is especially relevant for shortcodes that work with ACF or WP_Query. If a field is empty or a query returns no results, the shortcode may generate empty or broken HTML. In large projects, this complicates layout and can negatively affect a page’s appearance, even if the problem isn’t immediately visible.

Security is also often ignored. Data output via a shortcode should be escaped even if it is entered through the WordPress admin panel. This helps avoid invalid HTML issues and makes the code more stable over the long term. It’s also important to avoid tying shortcodes to a specific theme, because that complicates further site development and design changes.