For years, theme developers wishing to pass data to template files have had to use less than ideal workarounds. This included the use of global variables,
include( locate_template() ) pattern, or own version of
get_template_part(), and so on.
Starting in WordPress 5.5, the template loading functions will now allow additional arguments to be passed through to the matched template file using a new
To provide proper context, the related action hooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. have also been updated to pass this new
get_search_form() already accepts and passes additional arguments to search form templates as of . However, the
$args parameter was added to the related hooks at the same time as the ones above. These are:
search_form_format (filter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.)
'class' => 'user',
'arbitrary_data' => array(
'foo' => 'baz',
'bar' => true,
In the above example, the additional data passed to
get_template_part() through the
$args variable can be accessed within the
foo.php template through the locally scoped
// Example foo.php template.
// Set defaults.
$args = wp_parse_args(
'class' => '',
'arbitrary_data' => array(
'foo' => 'fooval',
'bar' => false,
<div class="widget <?php echo esc_html_class( $args['class'] ); ?>">
<?php echo esc_html( $args['arbitrary_data']['foo'] ); ?>
Note: Any template file that currently contains an
$args variable should take care when utilizing this new feature. Any modifications to
$args in the loaded template files will override any values passed through using the above functions.
This enhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. ticket Created for both bug reports and feature development on the bug tracker. was created 8 years ago, and is a long awaited addition. Thank you to all that helped discuss and refine this change.
For reference, see the related Trac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket: #21676.
Props @audrasjb and @desrosj for technical review and proofreading.