shortcode_atts( array $pairs, array $atts, string $shortcode = '' ): array

Combines user attributes with known attributes and fill in defaults when needed.

Contents

Description

The pairs should be considered to be all of the attributes which are supported by the caller and given as a list. The returned attributes will only contain the attributes in the $pairs list.

If the $atts list has unsupported attributes, then they will be ignored and removed from the final returned list.

Top ↑

Parameters

$pairs array Required
Entire list of supported attributes and their defaults.
$atts array Required
User defined attributes in shortcode tag.
$shortcode string Optional
The name of the shortcode, provided for context to enable filtering

Default: ''

Top ↑

Return

array Combined and filtered attribute list.

Top ↑

Source

File: wp-includes/shortcodes.php. View all references 

function shortcode_atts( $pairs, $atts, $shortcode = '' ) {
	$atts = (array) $atts;
	$out  = array();
	foreach ( $pairs as $name => $default ) {
		if ( array_key_exists( $name, $atts ) ) {
			$out[ $name ] = $atts[ $name ];
		} else {
			$out[ $name ] = $default;
		}
	}

	if ( $shortcode ) {
		/**
		 * Filters shortcode attributes.
		 *
		 * If the third parameter of the shortcode_atts() function is present then this filter is available.
		 * The third parameter, $shortcode, is the name of the shortcode.
		 *
		 * @since 3.6.0
		 * @since 4.4.0 Added the `$shortcode` parameter.
		 *
		 * @param array  $out       The output array of shortcode attributes.
		 * @param array  $pairs     The supported attributes and their defaults.
		 * @param array  $atts      The user defined shortcode attributes.
		 * @param string $shortcode The shortcode name.
		 */
		$out = apply_filters( "shortcode_atts_{$shortcode}", $out, $pairs, $atts, $shortcode );
	}

	return $out;
}

View on Trac View on GitHub

Top ↑

Hooks

Top ↑

Top ↑

Uses

Uses
Uses Description
apply_filters() wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Top ↑

Changelog

Changelog
Version Description
2.5.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 12You must log in to vote on the helpfulness of this note
    Contributed by Aaron T. Grogg —

    It might be really useful to note that attribute names must be all lowercase…

    If your shortcode looks like this:
    [shortcode attOne="foo" attTwo="bar"]
    The array passed to the callback function will look like this:
    Array( attone => "foo", atttwo => "bar" )

    So, I guess you could use camelCase in the shortcode, just remember to expect those camelCase to be all lowercase in your shortcode_atts…

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Example

    /**
 * Callback to register a bartag shortcode.
 *
 * @param array $atts Shortcode attributes.
 * @return string Shortcode output.
function wpdocs_bartag_func( $atts ) {
	$atts = shortcode_atts(
		array(
			'foo' => 'no foo',
			'bar' => 'default bar',
		), $atts, 'bartag' );

	return 'bartag: ' . esc_html( $atts['foo'] ) . ' ' . esc_html( $atts['bar'] );
}
add_shortcode( 'bartag', 'wpdocs_bartag_func' );

    [bartag foo=”koala” bar=”bears”] outputs the following:
    bartag: koala bears

    [bartag foo=”koala”] outputs the following:
    bartag: koala default bar

    This creates a “[bartag]” shortcode that supports two attributes: [bartag foo="something" bar="something else"]. Both attributes are optional and will take on default options if they are not provided.

  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by crstauf —

    Clarification on Aaron’s note:

    The case of the keys on the $pairs must match the keys on the $atts, or the value will be discarded.

    See these examples:

    print_r( shortcode_atts( array(
	'CAPITAL' => '1',
	'fooBar' => '2',
), array(
	'CAPITAL' => '3',
	'fooBar' => '4',
) ) );
// Output: Array ( [CAPITAL] => 3 [fooBar] => 4 )
    print_r( shortcode_atts( array(
	'CAPITAL' => '1',
	'fooBar' => '2',
), array(
	'capital' => '3',
	'fooBar' => '4',
) ) );
// Output: Array ( [CAPITAL] => 1 [fooBar] => 4 )
    print_r( shortcode_atts( array(
	'CAPITAL' => '1',
	'fooBar' => '2',
), array(
	'capital' => '3',
	'foobar' => '4',
) ) );
// Output: Array ( [CAPITAL] => 1 [fooBar] => 2 )
    print_r( shortcode_atts( array(
	'capital' => '1',
	'fooBar' => '2',
), array(
	'capital' => '3',
	'foobar' => '4',
) ) );
// Output: Array ( [capital] => 3 [fooBar] => 2 )
  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Tessa Watkins —

    To ensure this function works and allow for case insensitive attributes, I use array_change_key_case in a one-liner like this

    /**
 * My Custom Shortcode
 * 
 * @param array $atts Optional. An associative array of key/value attributes. Default is empty array.
 * @param string $content Optional. The content between the opening and closing shortcode tags. Default is an empty string.
 * @param string $tag Optional. The name of the shortcode, provided for context to enable filtering. Default is an empty string.
 * 
 * @return string shortcode output
 */
function tw_custom_shortcode($atts = array(), $content = '', $tag = '')
{
    $atts = shortcode_atts(array(), array_change_key_case((array)$atts, CASE_LOWER), $tag);

    //Do stuff, probably sanitize inputs

    $output = '';
    return $output;
}
add_shortcode('tw_custom', 'tw_custom_shortcode');
  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
    Contributed by zitomerh —

    I had to hunt around to find all the pieces, I hope others find this helpful.

    So, building on a previous example:

    /**
 * How to use shortcode callback parms with shortcode_atts to make
 * callback code flexible and re-useable.
 *
 * This allows filters to be applied to a callback depending on which
 * shortcode called it.
 *
 * @param array  $atts    Shortcode attributes.
 * @param string $content Shortcode content.
 * @param string $tag     The shortcode which invoked the callback
 * @return string Shortcode output.
 */
function my_callback_func( $atts, $content, $tag ) {
    $atts = shortcode_atts(
        array(
            'foo' => '',
            'bar' => '',
        ), $atts, $tag );

 //do something here(trivial example)
	if ( !empty($zoo) ) {
		return $zoo;  //where did $zoo come from? see below
	}
	else return $foo;
    
}

add_shortcode( 'myshortcode1', 'my_callback_func' );
add_shortcode( 'myshortcode2', 'my_callback_func' );

/* now make a filter that's applied ONLY when my_callback_func is invoked by myshortcode1 -
this example adds param 'zoo' to myshortcode1  */

add_filter ('shortcode_atts_myshortcode1', 'add_zoo', 10, 3);
function add_zoo ($out, $pairs, $atts ) {
	$out['zoo'] = '';
	return $out;
}
// Now we can use [myshortcode1 foo='myfoo' zoo='myzoo']  output: myzoo
// and [myshortcode2 foo='myfoo' zoo='myzoo']  output: myfoo

You must log in before being able to contribute a note or feedback.