shortcode_atts() │ WP 2.5.0

Processes the attributes (parameters) of the shortcode: adds default values when needed and removes inappropriate attributes.

The result will contain keys from the attribute values of the $atts parameter that are present in the $pairs parameter. That is, $pairs are the default parameters, and $atts are the passed parameters. The passed parameters cannot have keys that are not in the defaults. This is, in a way, a whitelist of shortcode attributes.

Be sure to read: Creating a Shortcode in WordPress

Hooks from the function

Returns

Array. The assembled and filtered list of attributes.

Usage

shortcode_atts( $pairs, $atts, $shortcode );
$pairs(array) (required)

An associative array that describes the possible attributes of the shortcode (these are the keys of the array) and their default values.

IMPORTANT! The keys of the $defaults array must be in lower-case. Do not use camelCase or UPPER-CASE, because in $atts the keys are always in lower-case.

$atts(array) (required)

An unfiltered array with the data that was specified in the shortcode. They will be compared with the array above.

$atts will contain an array of shortcode arguments that were specified by the user.

If a value is specified without a parameter name, it will be added to the indexed elements of the array. For example, for the shortcode [name value attr="val2" val3] we will get:

Array (
	[0]    => value
	[attr] => val2
	[1]    => val3
)

The attribute names (keys of the $atts array) are always converted to lower-case, while the values are not processed in any way. For example, if we specified the shortcode as [myshortcode FOO="BAR"], then in $atts we will get [ 'foo' => 'BAR' ].

$shortcode(string)

The name of the shortcode that will be used in the filter: shortcode_atts_{$shortcode}.

Since version 3.6, it passes the $atts parameter to the filter shortcode_atts_{$shortcode} if the $shortcode parameter is specified.

Default: ''

Examples

0

#1 Adding a shortcode

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

add_shortcode( 'bartag', 'shortcode_callback' );

function shortcode_callback( $atts ) {

	$atts = shortcode_atts( 
		[
			'foo' => 'no foo',
			'bar' => 'default bar',
		], 
		$atts, 
		'bartag' 
	);

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

/*
[bartag foo="koala" bar="bears"] outputs:
bartag: koala bears

[bartag foo=”koala”] outputs:
bartag: koala default bar
*/
0

#2 Letter case of the array keys $pairs and $atts are important!

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( [
		'CAPITAL' => '1',
		'fooBar'  => '2',
	], [
		'CAPITAL' => '3',
		'fooBar'  => '4',
	] 
) );
// Output: Array ( [CAPITAL] => 3 [fooBar] => 4 )

print_r( shortcode_atts( [
		'CAPITAL' => '1',
		'fooBar'  => '2',
	], [
		'capital' => '3',
		'foobar'  => '4',
	]
) );
// Output: Array ( [CAPITAL] => 1 [fooBar] => 2 )

As we can see shortcode_atts() makes a case-sensitive comparison between the first argument (array of supported attributes and their defaults) and the second argument (array of user-defined attributes in shortcode tag). But the user-defined attributes are normalized to lowercase by WordPress before being passed to the shortcode callback function (see shortcode_parse_atts()).

So NEWER use UPPERCASE characters in keys of supported attributes!

So the correct variant for above code will be:

$atts = shortcode_atts( [
		'capital' => '1',
		'foobar'  => '2',
	], $passed_atts
);

Changelog

Since 2.5.0 Introduced.

shortcode_atts() code WP 6.9.1

wp-includes/shortcodes.php 
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;
}

Shortcodes