Shortcodes 101 – Shortcode Attributes
## Metadata
- Author: [[Pippins Plugins]]
- Full Title: Shortcodes 101 – Shortcode Attributes
- Category: #articles
- Summary: In the Basics of the Shortcode API, we briefly covered shortcode attributes and the shortcode_atts() function.
- URL: https://pippinsplugins.com/shortcodes-101-shortcode-attributes/
In the [Basics of the Shortcode API](https://pippinsplugins.com/shortcodes-101-basics-shortcode-api/), we briefly covered shortcode attributes and the shortcode\_atts() function. Now it is time to dive deep into setting up attributes for shortcodes and learn a few tricks can that be exceptionally helpful when building shortcodes in your plugins or when modifying the shortcodes of other plugins.
Shortcode attributes are the “settings” that users can specify in the shortcode when using it on a post or page. In the following example, “color” is the attribute and “blue” is the value of the attribute:
```
[pw101_box color="blue"]
```
Shortcodes can have more than one attribute:
```
[pw101_box color="green" border="none" icon="alert"]
```
These attributes can be used to control what your shortcode outputs, but in order to do that, we need to have a way retrieve the values of each attribute specified. That’s where the [shortcode\_atts()](http://codex.wordpress.org/Function_Reference/shortcode_atts) function comes in.
The function is quite simple. It has three parameters:
* $pairs – a array of key => value pairs that defines the default values of all attributes
* $atts – the attributes supplied by the user
* $shortcode – the shortcode tag (pw101\_box)
Take the following example.
```
function pw101_box_shortcode( $atts, $content = null ) {
$atts = shortcode_atts( array(
'color' > 'blue',
'icon' > '',
'border' > '2px'
), $atts, 'pw101_box' );
return $box;
}
add_shortcode( 'pw101_box', 'pw101_box_shortcode' );
```
First, *$atts* is initially setup by WordPress since it is the first parameter available in our add\_shortcode() callback. This $atts will contain all attributes that the user has included in the shortcode.
Second, we create a new *$atts* variable and use shortcode\_atts() to setup its value. What does this do? It takes the user-supplied attributes and combines them with our default attributes. The first parameter passed to the shortcode\_atts() function is an array of defaults. We have set the defaults to:
* color: blue
* icon: (none)
* border: 2px
If no attributes are supplied by the user, these are the three values our shortcode will use. If only the color attribute is specified, and it is set to “red”, the following values will be used:
* color: red
* icon: (none)
* border: 2px
The shortcode\_atts() function is exceptionally useful because it lets us easily define the standard values for our shortcode attributes without having to setup our own logic processing for them.
The third parameter to the shortcode\_atts() function is extremely valuable but often under utilized. It allows you to define the name of the filter that your shortcode attributes go through before being returned by shortcode\_atts(). WordPress returns the attributes through a filter called *shortcode\_atts\_$shortcode*, so in our example, the filter would be *shortcode\_atts\_pw101\_box.* This filter allows the attributes to be modified from other places in your plugin or even entirely separate plugins.
I’d suggest looking at the [source code of the filter in WordPress core](https://core.trac.wordpress.org/browser/tags/4.0/src/wp-includes/shortcodes.php#L371).
I recently used this filter in an extension for Easy Digital Downloads. EDD has a shortcode called [downloads] that takes a lot of attributes. For my extension to work properly, I had to force one of the attributes to always be a specific value, so I used the *shortcode\_atts\_downloads* filter to modify the attribute before it is returned, therefor ensuring that it was always the value I needed it to be.
Once you have the shortcode attributes setup, you can easily use this inside of your shortcode to modify the final output. Earlier we used this example:
```
function pw101_box_shortcode( $atts, $content = null ) {
$atts = shortcode_atts( array(
'color' => 'blue',
'icon' => '',
'border' => '2px'
), $atts, 'pw101_box' );
$box = '<div class="pw-box ' . esc_attr( $atts['color'] ) . ">';
$box .= $content;
$box .= '</div>';
return $box;
}
```
Here you can see the *class* attribute of the DIV tag being set based on the value of *color* attribute in our shortcode.
Since we have an *icon* attribute, let’s go ahead and set that up too:
```
function pw101_box_shortcode( $atts, $content = null ) {
$atts = shortcode_atts( array(
'color' => 'blue',
'icon' => '',
'border' => '2px'
), $atts, 'pw101_box' );
$box = '<div class="pw-box ' . esc_attr( $atts['color'] ) . ">';
if( ! empty( $atts['icon'] ) ) {
$box .= '<span class="icon icon-' . esc_attr( $atts['icon'] ) . '"></span>';
}
$box .= $content;
$box .= '</div>';
return $box;
}
```
If the *icon* attribute is specified, we simply output a simple SPAN tag with a class that can then be styled in our CSS.
We can do the same thing with the *border* attribute:
```
function pw101_box_shortcode( $atts, $content = null ) {
$atts = shortcode_atts( array(
'color' => 'blue',
'icon' => '',
'border' => '2px'
), $atts, 'pw101_box' );
$box = '<div class="pw-box ' . esc_attr( $atts['color'] ) . " style="border-width: ' . esc_attr( $atts['border'] ) . ';">';
if( ! empty( $atts['icon'] ) ) {
$box .= '<span class="icon icon-' . esc_attr( $atts['icon'] ) . '"></span>';
}
$box .= $content;
$box .= '</div>';
return $box;
}
```, Shortcodes 101 – Shortcode Attributes, Pippins Plugins, 01gnmczycs41c41a1shz7w8ees.