WordPress shortcodes let you place a registered tag in content and have WordPress replace it with a callback’s returned string. To use them reliably, choose a distinctive tag, register one handler, define and secure its attributes, return rather than echo output, and account for how enclosed content and nested shortcodes are parsed.
1. Choose a distinctive, lowercase shortcode tag
A shortcode is a content macro: WordPress recognizes its registered tag and substitutes the handler’s output where the tag appears. The API supports both self-closing tags, such as [itech_notice], and enclosing forms, such as [itech_notice]Text here[/itech_notice]. Shortcodes were introduced in WordPress 2.5. See the Shortcode API reference.
Use a lowercase name that is unlikely to overlap with a tag from a theme or plugin. WordPress advises against hyphens in shortcode names; a unique prefix is a practical way to reduce collisions. Keep the tag focused on one purpose so editors can understand what it does.
2. Register one clear callback
Register the tag with add_shortcode(), typically from plugin code or a theme’s setup code:
Recommended Free Tools
add_shortcode( 'itech_notice', 'itech_notice_shortcode' );
function itech_notice_shortcode( $atts = array(), $content = null, $tag = '' ) {
return '<div class="itech-notice">Notice</div>';
}The callback can receive attributes, enclosed content, and the tag itself. Attributes may be absent, so give them suitable defaults. A shortcode tag can have only one active callback: registering the same name again replaces the previous handler. Avoid duplicate registrations that can silently change the shortcode’s behavior. The Shortcodes section of the Plugin Handbook explains registration and callback behavior.
3. Define and document accepted attributes
Use shortcode_atts() to set defaults and restrict the attributes your callback will use. For example:
function itech_notice_shortcode( $atts = array(), $content = null, $tag = '' ) {
$atts = shortcode_atts(
array(
'type' => 'info',
'title' => '',
),
$atts,
'itech_notice'
);
$type = sanitize_key( $atts['type'] );
$title = sanitize_text_field( $atts['title'] );
return '<div class="itech-notice itech-notice--' . esc_attr( $type ) . '">'
. '<strong>' . esc_html( $title ) . '</strong>'
. '</div>';
}Here, type and title are the supported attributes; unrecognized keys are discarded when the values are normalized against the defaults. Tell editors which attributes exist, what values they accept, and what happens when they omit one. WordPress lowercases attribute keys during processing, so use lowercase names consistently. See Shortcodes with Parameters.
4. Return a string instead of echoing
A shortcode callback must return its output. WordPress inserts the returned string at the shortcode’s position in the content; echoing can send markup to the wrong place or disrupt page output. For a short string, concatenate the markup and values as in the example above. For longer templates, the API reference demonstrates output buffering as a way to capture generated HTML into a string before returning it.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteShortcode output does not receive normal paragraph and line-break formatting in the same way as surrounding content. If the result needs paragraphs or other structure, return appropriate block markup yourself rather than relying on WordPress to add it.
5. Handle self-closing and enclosing forms deliberately
If the shortcode should accept enclosed content, give the callback’s $content parameter a default of null. That lets the handler distinguish a self-closing use from an enclosing one. Decide what each form means and produce the corresponding output; do not assume the enclosed content is safe just because it came from a post.
Content inside an enclosing shortcode can contain raw HTML. Validate and sanitize any values you use, and escape or filter content for the context where you output it. WordPress’s Enclosing Shortcodes guide covers the callback pattern and its responsibility for handling enclosed content.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.6. Sanitize inputs and escape output for its context
Sanitization and escaping solve different problems: sanitize or validate incoming values to ensure they meet expectations, then escape values when inserting them into output. Choose an escaping function based on the exact destination:
esc_html()for text inside HTML.esc_attr()for an HTML attribute.esc_url()for a URL.wp_kses_post()when permitted post-style HTML should be retained.
Do not treat all output as plain text or apply one escaping function indiscriminately. For example, a value inserted into an href needs URL escaping, while a value inserted into visible text needs HTML escaping. WordPress explains these context-specific choices in Escaping Data and its Security handbook.
7. Test nesting and where shortcodes run
WordPress processes shortcodes when the content is displayed, with do_shortcode() attached by default to the_content at priority 11. That does not mean enclosed content is automatically parsed again: the shortcode parser’s single pass does not recursively process a shortcode found inside another shortcode’s enclosed content.
If nested shortcodes are an intended feature, explicitly call do_shortcode() on the relevant content and document that behavior. Test both self-closing and enclosing uses, including any nested cases editors are expected to write. The API also documents a limitation when the same tag is mixed between enclosing and non-enclosing forms. See the Shortcode API reference and the enclosing-shortcodes guidance.
Keep registrations focused: the API reference cautions that registration becomes unstable with hundreds of shortcode names and recommends relying on a small number. This is a reason to avoid proliferating tags, not a published performance benchmark.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →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.
