How to Create a Custom Shortcode in WordPress

Key points:

• WordPress shortcodes are small pieces of code that add dynamic content to websites.
• However, they come with risks like security vulnerabilities and limited functionality.
• While you can create custom shortcodes manually or using the Advanced Custom Fields (ACF^®) plugin, ACF Blocks are a better alternative.
• They are easier to use, integrate better with the WordPress block editor, and allow developers to create reusable, customizable blocks.

If you’ve ever needed to add custom features across multiple WordPress pages, you know the challenge. Whether it’s a contact form, pricing table, or product grid, your options are limited. You either end up copying chunks of code or installing multiple plugins, and neither option is particularly elegant.

For years, WordPress developers have relied on shortcodes to solve this problem. These snippets let you access complex features with simple commands. Just type a few characters, and your custom element appears exactly where you want it.

However, while shortcodes are incredibly useful, they might not be your best option anymore. Modern WordPress development offers alternatives like ACF Blocks, a feature of the PRO version of Advanced Custom Fields (ACF^®), that provide better flexibility and a more intuitive editing experience.

We’ll cover both approaches: First, the traditional shortcode method you might need for existing projects, and second, the modern block-based solution that could be a better fit for your needs.

What are WordPress shortcodes?

WordPress shortcodes are simple commands that you add to your posts or pages using square brackets, like [caption],[gallery], or [contact_form]. While they look basic on the surface, they actually add complex features to your site without requiring you to write complicated code.

When WordPress loads your page, it sees these shortcodes and automatically replaces them with their corresponding functionality. For example, a simple [contact_form] shortcode might expand into a complete form with input fields, validation, and submission handling.

You’ll find shortcodes everywhere in WordPress. Some come built into WordPress itself for basic features like embedding content. Others can be found with your themes and plugins, adding their own specific functionality. You can even create custom shortcodes tailored to your site requirements, like a custom call to action (CTA) button.

Shortcodes are particularly useful for: 

• Displaying dynamic features such as forms, buttons, or social media feeds.
• Reducing repetitive tasks by reusing custom functionalities.
• Embedding multimedia like videos, galleries, or audio players.

Understanding the risks and limitations of WordPress shortcodes

Security vulnerabilities

Poorly implemented shortcodes can expose sensitive data to unauthorized users. When shortcodes access database information or private content, they need careful access control implementation. 

A common mistake is assuming that hiding the shortcode itself provides security. Spoiler: It doesn’t. Any user who discovers your shortcode syntax could potentially access restricted information if proper validation isn’t in place.

Performance considerations

While individual shortcodes might seem lightweight, their impact compounds quickly. Each shortcode requires WordPress to execute PHP functions during page load. 

On content-heavy pages or high-traffic sites, this processing overhead can significantly affect load times. This becomes especially noticeable when shortcodes make database queries or API calls.

Theme and plugin dependencies

Shortcodes often rely on specific theme functions or plugin code to work properly. When you switch themes or deactivate plugins, any shortcodes tied to them will break.

This creates what developers call “shortcode lock-in,” where your content becomes dependent on specific plugins staying active, limiting your ability to make changes to your site.

For uses of the ACF shortcode specifically, they will cease to function if the ACF plugin is deactivated or if the referenced field groups are deleted or modified.

Development limitations

Traditional shortcodes lack modern development features like live preview or visual editing. They’re essentially blind inputs until the page renders. This makes them particularly challenging for content editors who need to see how their changes will look in real time. 

Modern block-based solutions, like those built with ACF, offer more sophisticated development options with better user experiences.

How to create and use your first custom WordPress shortcode

Building a custom shortcode takes three steps: writing a function, setting up what it displays, and telling WordPress it exists. While you’ll need to write some code, this method gives you the most freedom to create exactly what you want. Before you begin, it’s a good idea to back up your WordPress site.

1. Create the function

Start by writing a simple PHP function that runs whenever someone uses your shortcode. Add this to your theme’s functions.php file, a custom plugin, or a must-use plugin (mu-plugin):

function my_shortcode_function($atts, $content = null) {
    // Logic for the shortcode goes here
    return "Hello, World!";
}

2. Define the output

Here’s where you determine what your shortcode actually displays. Your function can handle both attributes (parameters that customize the output) and content placed between shortcode tags. The $atts parameter manages your attributes, while $content handles any text between [shortcode]content[/shortcode]:

$atts = shortcode_atts(
    array('name' => 'World'), // Default attributes
    $atts // User-defined attributes
);
return "Hello, " . esc_html($atts['name']) . "!";

3. Register the shortcode

Finally, you’ll register your shortcode with WordPress using the add_shortcode() function. This step makes your shortcode available throughout your site, including in posts, pages, and widgets:

add_shortcode('my_shortcode', 'my_shortcode_function');

Here’s the complete code that brings it all together:

function my_shortcode_function($atts, $content = null) {
    // Set default attributes and merge with user-defined attributes
    $atts = shortcode_atts(
        array(
            'name' => 'World', // Default value for the 'name' attribute
        ),
        $atts
    );

    // Generate the output
    $output = "Hello, " . esc_html($atts['name']) . "!";

    // Return the output
    return $output;
}

// Register the shortcode
add_shortcode('my_shortcode', 'my_shortcode_function');

Using your new shortcode

Once registered, you can use your shortcode in several ways:

• Basic usage: [my_shortcode].
• With attributes: [my_shortcode name="Alice"].

Add your shortcode through the block editor or in widgets by adding a Text widget or Shortcode block to your sidebar or footer.

Here’s what it looks like in the editor:

And here’s what it looks like on the frontend:

The better alternative to shortcodes: ACF Blocks

While shortcodes have been a WordPress staple, they pose real security risks that make them a less-than-ideal choice for modern development. A better solution exists: ACF Blocks, a feature of ACF PRO that offers a more intuitive user experience.

ACF Blocks allow you to create custom Gutenberg blocks without diving deep into JavaScript or frontend frameworks like React. They provide all the flexibility of shortcodes while integrating with the block editor.

You get visual editing right in Gutenberg, direct integration with your ACF fields, and better security. Plus, you can preview your changes in real time, something shortcodes simply can’t offer.

How to create and use ACF Blocks

Ready to build your first ACF Block? Let’s create one that displays a custom title field. You’ll need ACF PRO installed and an existing ACF field with the key ‘title’.

1. Create a folder in your child theme’s folder called Blocks and add files: block.json, template.php, style.css.
2. Add to block.json:

{
  "name": "my-theme/my-custom-block",
  "title": "My Custom Block",
  "description": "A simple ACF block.",
  "category": "widgets",
  "icon": "smiley",
  "keywords": ["custom", "acf"],
  "supports": {
    "align": true
  },
  "acf": {
    "mode": "preview",
    "renderTemplate": "template.php"
  },
  "style": "file:./style.css"
}

3. Add to template.php:

<?php
$title = get_field('title'); // ACF field
?>
<div class="custom-block">
  <p>This is my custom block!</p>
</div>

4. Add to style.css:

.custom-block {
  padding: 20px;
  background: #f9f9f9;
  border: 1px solid #ddd;
}

5. Open your theme’s functions.php file and add this code to register your block: 

<?php
function mytheme_register_acf_blocks() {
    register_block_type(__DIR__ . '/blocks/my-custom-block');
}

add_action('init', 'mytheme_register_acf_blocks');

Once you’ve added all these files, your new block will be available in the Gutenberg editor.

Advanced users can enhance blocks using the Block Bindings API to connect ACF data directly to core block attributes without custom PHP templates.

Personalize your WordPress site with ACF

Throughout this guide, we’ve explored how shortcodes work as snippets of code that add dynamic features to WordPress sites. While they’re useful for embedding forms, galleries, and custom content, their security risks and maintenance challenges point to the need for better solutions.

ACF offers exactly that. With ACF Blocks, developers get a more secure and intuitive way to display custom field values in WordPress. Creating these blocks doesn’t require deep JavaScript knowledge – just familiar PHP skills and basic WordPress development experience.

Plus, connecting blocks to your custom fields is straightforward, making it easier to build and maintain dynamic content.

Ready to build better WordPress features? Upgrade to ACF PRO and start creating secure, user-friendly blocks today.