Recommended Free Tools
To run a shortcode from a WordPress theme template, pass the complete bracketed string to do_shortcode() and print the returned value:
<?php echo do_shortcode( '' ); ?>This is different from writing a shortcode in post content, where WordPress normally processes it during the_content. In a PHP template, you must call do_shortcode() yourself. If you are creating the shortcode, register a unique tag with add_shortcode() and have its callback return the replacement HTML or text.
What a WordPress shortcode does
A shortcode is a bracketed token such as . WordPress looks for a registered tag, calls that tag’s callback, and replaces the token with the callback’s returned content. The Shortcode API was introduced in WordPress 2.5. The official overview explains registration, attributes, enclosed content and parser behavior at the WordPress Shortcode API.
A shortcode only works while its handler is registered. If a plugin is deactivated, a theme’s registration code is unavailable, or the tag is misspelled, the bracketed text can remain visible.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →#1 Best Overall
Run an existing shortcode in a theme template
Use the full shortcode, including square brackets, as the argument to do_shortcode():
<?php echo do_shortcode( '' ); ?>For attributes, put them inside the shortcode string:
<?php echo do_shortcode( '' ); ?>This gallery pattern is also shown in the WordPress Theme Handbook. The do_shortcode() reference documents that the function returns the processed string. If no registered shortcode tags are available, it returns the input without processing.
Where to place the call
Put the call in the template where the output should appear, such as a classic theme’s page, single-post or custom template file:
<?php
if ( shortcode_exists( 'gallery' ) ) {
echo do_shortcode( '' );
}
?>The existence check is optional, but it lets a template avoid outputting a literal shortcode when the expected plugin or registration is missing. The Plugin Handbook’s basic shortcode examples covers checking registered tags.
Existing shortcode or custom shortcode?
| Situation | What to do | Where the string comes from |
|---|---|---|
| A plugin or WordPress feature already provides the tag | Call do_shortcode() in the template |
A literal string you write, or a value you construct safely |
| You need new behavior and no handler exists | Register a tag with add_shortcode(), then invoke it |
Your template, post content, widget or another supported context |
| The shortcode represents site functionality that should survive a theme switch | Prefer registering it outside the presentation theme as a maintainability choice | Any context that calls the registered tag |
WordPress’s references define the API but do not require every custom shortcode to live in a plugin or every shortcode to live in a theme. Keeping durable site functionality outside a theme can prevent its disappearance when the design is changed; a presentation-only shortcode may reasonably remain with the theme.
Register a custom shortcode
Register a distinctive tag and return the replacement content from its callback:
<?php
function site_example_shortcode( $atts = [], $content = null ) {
return '<span class="example">Example output</span>';
}
add_shortcode( 'site_example', 'site_example_shortcode' );
?>Then execute it in a template:
<?php echo do_shortcode( '[site_example]' ); ?>The callback must return output; it should not echo it. The add_shortcode() reference also notes that a later registration using the same tag takes precedence, so choose a distinctive name and avoid collisions. The API cautions against hyphens in shortcode tags.
Add attributes with defaults
WordPress supplies attributes as an array. Normalize them with shortcode_atts(), use lowercase attribute names, and escape values for the context in which they are output:
Rank #4
<?php
function site_greeting_shortcode( $atts = [] ) {
$atts = shortcode_atts(
[ 'name' => 'friend' ],
$atts,
'site_greeting'
);
return 'Hello, ' . esc_html( $atts['name'] ) . '!';
}
add_shortcode( 'site_greeting', 'site_greeting_shortcode' );
?>These inputs produce different results:
<?php
echo do_shortcode( '[site_greeting]' );
echo do_shortcode( '[site_greeting name="Taylor"]' );
?>shortcode_atts() keeps the defaults you declare and ignores unknown attributes. The API details this callback signature and normalization behavior at developer.wordpress.org/apis/shortcode/.
Accept enclosed content
An enclosing shortcode has an opening and closing tag:
[notice]Text inside the shortcode[/notice]The callback receives the enclosed text as its $content argument:
<?php
function site_notice_shortcode( $atts = [], $content = null ) {
$text = $content === null ? '' : esc_html( $content );
return '<div class="notice">' . $text . '</div>';
}
add_shortcode( 'notice', 'site_notice_shortcode' );
?>Raw enclosed content is the callback author’s responsibility: escape it or deliberately filter it before including it in returned markup. If the shortcode is intended to allow safe nested shortcodes, the callback can call do_shortcode( $content ), but recursive processing should be designed carefully to avoid unexpected recursion or markup.
Why a shortcode appears literally
The handler is not registered
do_shortcode() cannot process a tag whose callback has not been registered. Confirm that the plugin is active or that the registration code runs before the template executes.
The tag or attributes are wrong
Compare spelling, underscores and attribute names with the registration. Use the exact bracketed form, for example [site_greeting name="Taylor"], not just site_greeting.
The template is printing the string directly
This prints brackets as text:
<?php echo ''; ?>Execute it instead:
<?php echo do_shortcode( '' ); ?>A duplicate tag replaced your callback
If another component registers the same tag later in the load order, its callback wins. Rename your tag with a project-specific prefix rather than relying on a generic name such as box or button.
Nested enclosing tags behave unexpectedly
The shortcode parser performs a documented single parsing pass, and same-name nested enclosing shortcodes are a limitation. A callback must explicitly process enclosed content when nested behavior is part of its design; do not assume that identical nested tags will be interpreted as a tree automatically.
安全 output and maintenance checklist
- Call
do_shortcode()with the complete bracketed string. - Verify that the shortcode is registered before the template runs.
- Use a distinctive tag and remember that later duplicate registrations override earlier ones.
- Normalize declared attributes with
shortcode_atts(). - Escape attribute values and enclosed content for their output context.
- Return callback output instead of echoing it.
- Keep functionality that must survive a theme change outside the theme when that maintenance goal applies.
- Test empty, missing and unexpected attribute values, plus any enclosed HTML your callback accepts.
When to use a shortcode in a template
Use a template call when the placement belongs to the theme’s PHP structure but the output is already supplied by a registered shortcode—for example, rendering a gallery in a custom layout. Use normal post content when editors should control placement inside the editor. Build a custom shortcode only when a reusable, editor-friendly token is genuinely useful; otherwise, direct template markup is often clearer for a fixed design element.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
