Understanding WordPress’ $args variable – $args ye scurvy lads

Posted by Pixafy Team | Monday, April 15, 2013

$args. What is this $args? If you’ve ever seen this before in the WordPress codex or in a template, you might have already asked yourself two things. One, what the heck do people do with this? Two, why does it look synonymous to pirate lingo?

All jokes aside, $args is a common variable to come across in WordPress that you’ll usually see with snippets that begin with “wp_” (e.g. wp_get_archives, wp_list_comments, wp_get_recent_posts). $args stands for “arguments” and variables are values given that represent something else. It’s normally used to pass along these values faster and cleaner. For example, let’s say you have:

<?php echo ( ‘I have apple pie, cherry pie, and blueberry pie.’); ?>

But instead of writing the word “pie” three times, you can write:

$pie = 'pie';
echo("I have apple $pie, cherry $pie, and blueberry $pie ");

The variable $pie is a stand in for another value, in this case, the word “pie”. It can be grabbed at any time, and if that value were to ever to change, like maybe we’d want all the places that say “pie” to now say “cake”, why change it in every place it’s being used when you can just change the value of the variable?

Now that we know a bit on how handy variables are, $args is a variable with a collection of values that can be called, or rather an array, an array of arguments. If you’re just copying and pasting from the Codex without really understanding what this is for, you could be missing out on all the options that PHP in WordPress has to offer.

To explain $args and the power behind it, we’re going to use WordPress’  handy PHP snippet for listing categories:

<?php wp_list_categories( $args ); ?>

When this snippet is looked up in the Codex, the array that we need is written out for us.

Now we can use wp_list_categories as is, without anything inside the parentheses, and it will list the categories following what is default in WordPress  These details are listed on the Codex page. But if we do want to take advantage of $args, we can leave it inside the parentheses and build our array of arguments with what we want.

So our code will look something like this, with the variable and it’s value, in our case, $args and it’s array of values, placed before it is used in wp_list_categories:

$args = array(
            'show_option_all'    => '',
            'orderby'            => 'name',
            'order'              => 'ASC',
            'style'              => 'list',
            'show_count'         => 0,
            'hide_empty'         => 1,
            'use_desc_for_title' => 1,
            'child_of'           => 0,
            'feed'               => '',
            'feed_type'          => '',
            'feed_image'         => '',
            'exclude'            => '',
            'exclude_tree'       => '',
            'include'            => '',
            'hierarchical'       => 1,
            'title_li'           => __( 'Categories' ),
            'show_option_none'   => __('No categories'),
            'number'             => null,
            'echo'               => 1,
            'depth'              => 0,
            'current_category'   => 0,
            'pad_counts'         => 0,
            'taxonomy'           => 'category',
            'walker'             => null


Now if we use this array as is, it will be the same as using the default values that wp_list_categories already comes with because we haven’t changed anything. With an $args array, you don’t have to include every single option that it has to offer unless it’s something that you’re changing.

So let’s say we want a list of categories that are listed in descending order, that show the ones that aren’t assigned to any posts, and only show up to 10 categories. So if we look at the options we have and their explanations on the codex, we can just list in the array what we need. In our case, we need order, hide_empty, and number.

$args = array(
            'order'              => 'DESC',
            'hide_empty'         => 0,
            'number'             => ‘10’


We’ve changed the values above according to what we want and the Codex’s instructions. The Codex tells you how to change the values by either using a Boolean: True or False (which is 1 or 0 in WordPress), an Integer: a number, or a String: a series of characters. So if the value of something should be an integer, like ‘number’ for example, and we write the word ‘ten’ as the value instead of ’10’, it won’t work because integers can only contain numbers. For every value that you do not specify in your $args, WordPress will assume the default.

And there you have it. Now our list displays in descending order, shows categories regardless of whether they’re assigned to posts or not, and it will only show 10 categories.

One last note to remember: we don’t have to keep $args as $args. Since this is our stand in for something else, we have the power to change it. So $args can be $catList or $categoriez or $whateverYouWant.

And if we have wp_list_categories($args) and wp_get_archives($args) on a page, this can cause conflict unless the $args array has common values they both can share. If not, then there will be two variables and two arrays for each of these – they should not match.

$categoriez = array(
            'order'              => 'DESC',
            'hide_empty'         => 0,
            'number'             => ‘10’

$archivez = array(
            'type'              => 'weekly',
            ‘limit'         => ‘5’


There’s the power of $args at your fingertips – freedom to change the variable name and the array of arguments as you see fit. $Args ye landlubbers, I bid ye a grand adventure in WordPress!

Have any great tips for us? We’d love to hear them, so leave us a comment!