the_widget( string $widget, array $instance = array(), array $args = array() )

Output an arbitrary widget as a template tag.

Parameters

$widget

(string) (Required) The widget's PHP class name (see class-wp-widget.php).

$instance

(array) (Optional) The widget's instance settings.

Default value: array()

$args

(array) (Optional) Array of arguments to configure the display of the widget.

  • 'before_widget'
    (string) HTML content that will be prepended to the widget's HTML output. Default <div class="widget %s">, where %s is the widget's class name.
  • 'after_widget'
    (string) HTML content that will be appended to the widget's HTML output. Default </div>.
  • 'before_title'
    (string) HTML content that will be prepended to the widget's title when displayed. Default <h2 class="widgettitle">.
  • 'after_title'
    (string) HTML content that will be appended to the widget's title when displayed. Default </h2>.

Default value: array()

More Information

For parameter $widget, The classes for the widgets included with WordPress are:

Archives widget

Display a monthly archive list.


 <?php the_widget( 'WP_Widget_Archives', $instance, $args ); ?> 

  • widget’s classname: widget_archive
  • instance:
    title
    The title of archive list. Default: __('Archives')
    count
    Display number of posts in each archive (1). The show_post_count parameter of wp_get_archives. Default: 0 (hide)
    dropdown
    Display as drop-down list (1). Default: 0 (an unordered list)

Examples

Default usage:
 <?php the_widget( 'WP_Widget_Archives' ); ?> 

Display drop-down list:
 <?php the_widget( 'WP_Widget_Archives', 'dropdown=1' ); ?> 

Calendar widget

Displays a Calendar.


 <?php the_widget( 'WP_Widget_Calendar', $instance, $args ); ?> 

  • widget’s classname: widget_calendar
  • instance:
    title
    The title of calendar. Default:

Example

Default usage:
 <?php the_widget( 'WP_Widget_Calendar' ); ?> 

Categories widget

Displays a list of categories.


 <?php the_widget( 'WP_Widget_Categories', $instance, $args ); ?> 

  • widget’s classname: widget_categories
  • instance:
    title
    The title of categories list. Default: __( 'Categories' )
    count
    Display number of posts in each category. The show_count parameter of wp_dropdown_categories or wp_list_categories. Default: 0 (hide)
    hierarchical
    Display sub-categories as nested items inside the parent category (1). Default: 0 (in-line)
    dropdown
    Display as dropdown list (1). Default: 0 (an unordered list)

Examples

Default usage:
 <?php the_widget('WP_Widget_Categories'); ?> 

Display a dropdown list with number of posts.
 <?php the_widget( 'WP_Widget_Categories', 'dropdown=1&count=1' ); ?> 

Custom HTML widget

Displays arbitrary HTML.
 <?php the_widget( 'WP_Widget_Custom_HTML', $instance, $args ); ?> 

  • widget’s classname: widget_custom_html
  • instance:
    title
    The title for the content. Default:
    content
    arbitrary HTML. Default:

Examples

Default usage:
 <?php the_widget('WP_Widget_Custom_HTML', array('title' => 'Example', 'content' => '<p>Basic example.</p>')); ?> 

Displays a list of links (blogroll) in categories.


 <?php the_widget( 'WP_Widget_Links', $instance, $args ); ?> 

  • widget’s classname:
  • instance:
    title
    The title of the Links section.
    category
    Link category IDs , separated by commas, to display. The category parameter of wp_list_bookmarks. Default: false (display all of link categories)
    description
    Display description of link (1 – true). The show_description parameter. Default: false (hide)
    rating
    Display rating of link (1- true). The show_rating parameter. Default: false (hide)
    images
    Display image of link (1 – true). The show_images parameter. Default: true (show)
    name
    If display link image, output link name to the alt attribute. The show_name parameter. Default: false

Examples

Default usage:
 <?php the_widget( 'WP_Widget_Links' ); ?> 

Display lists in category IDs 2 or 3:
 <?php the_widget( 'WP_Widget_Links', 'category=2,3' ); ?> 

Meta widget

Display site meta. (Log in/out, admin, feed and WordPress links )


 <?php the_widget( 'WP_Widget_Meta', $instance, $args ); ?> 

  • widget’s classname: widget_meta
  • instance:
    title
    The title of meta section. Default: __( 'Meta' )

Example

Default usage:
 <?php the_widget( 'WP_Widget_Meta' ); ?> 

Pages widget

Display a list of Pages.


 <?php the_widget( 'WP_Widget_Pages', $instance, $args ); ?> 

  • widget’s classname: widget_pages
  • instance:
    title
    The title of Pages list. Default: __( 'Pages' )
    sortby
    The sort_column parameter of wp_list_pages. Default: menu_order
    exclude
    Page IDs, separated by commas, to be excluded from the list. Default: null (show all of Pages)

Examples

Default usage:

 the_widget( 'WP_Widget_Pages' );

Contents

as the heading, sort by last modified date:

 the_widget('WP_Widget_Pages', 'title=Contents&sortby=post_modified', 'before_title=<h3>&after_title=</h3>');

Recent Comments widget

Display to a list of recent comments.


 <?php the_widget( 'WP_Widget_Recent_Comments', $instance, $args ); ?> 

  • widget’s classname: widget_recent_comments
  • instance:
    title
    The title of comment list. Default: __( 'Recent Comments' )
    number
    Number of comments to show (at most 15). Default: 5

Example

Default usage:
 <?php the_widget( 'WP_Widget_Recent_Comments' ); ?> 

Recent Posts widget

Display to a list of recent posts.


 <?php the_widget( 'WP_Widget_Recent_Posts', $instance, $args ); ?> 

  • widget’s classname: widget_recent_entries
  • instance:
    title
    The title of post list. Default: __('Recent Posts')
    number
    Number of posts to show (at most 15). Default: 10

Example

Default usage:
 <?php the_widget( 'WP_Widget_Recent_Posts' ); ?> 

RSS widget

Display a list of entries from any RSS or Atom feed.


 <?php the_widget( 'WP_Widget_RSS', $instance, $args ); ?> 

  • widget’s classname:
  • instance :
    title
    The title of list
    Default: the title inherited from the RSS or Atom feed
    url
    RSS or Atom feed URL to include.
    items
    the number of RSS or Atom items to display
    show_summary
    show_author
    show_date

Example

Default usage:
 <?php the_widget( 'WP_Widget_RSS' ); ?> 

Search widget


 <?php the_widget( 'WP_Widget_Search', $instance, $args ); ?> 

  • widget’s classname: widget_search
  • instance:
    title
    The title of search form. Default: null

Example

Default usage:
 <?php the_widget( 'WP_Widget_Search' ); ?> 

Tag Cloud widget


 <?php the_widget( 'WP_Widget_Tag_Cloud', $instance, $args ); ?> 

  • widget’s classname:
  • instance:
    title
    The title of tag cloud. default: __( 'Tags' )
    taxonomy
    The taxonomy the cloud will draw tags from. default: post_tag

Example

Default usage:
 <?php the_widget( 'WP_Widget_Tag_Cloud' ); ?> 

Text widget


 <?php the_widget( 'WP_Widget_Text', $instance, $args ); ?> 

  • widget’s classname: widget_text
  • instance:
    • title
    • text
    • filter

Example

Default usage:
 <?php the_widget( 'WP_Widget_Text' ); ?> 

Custom Widget

Display custom widget in template.


 <?php the_widget( 'My_Custom_Widget', $instance, $args ); ?> 

  • widget’s classname: WIDGET CLASS NAME (for example see below)
  • instance: (optional)
  • arguments: (optional)

Example

Default usage:

class My_Custom_Widget extends WP_Widget
{
/* your code* /
}


 <?php the_widget( 'My_Custom_Widget' ); ?> 

Source

File: wp-includes/widgets.php 

function the_widget( $widget, $instance = array(), $args = array() ) {
	global $wp_widget_factory;

	if ( ! isset( $wp_widget_factory->widgets[ $widget ] ) ) {
		_doing_it_wrong(
			__FUNCTION__,
			sprintf(
				/* translators: %s: register_widget() */
				__( 'Widgets need to be registered using %s, before they can be displayed.' ),
				'<code>register_widget()</code>'
			),
			'4.9.0'
		);
		return;
	}

	$widget_obj = $wp_widget_factory->widgets[ $widget ];
	if ( ! ( $widget_obj instanceof WP_Widget ) ) {
		return;
	}

	$default_args          = array(
		'before_widget' => '<div class="widget %s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h2 class="widgettitle">',
		'after_title'   => '</h2>',
	);
	$args                  = wp_parse_args( $args, $default_args );
	$args['before_widget'] = sprintf( $args['before_widget'], $widget_obj->widget_options['classname'] );

	$instance = wp_parse_args( $instance );

	/** This filter is documented in wp-includes/class-wp-widget.php */
	$instance = apply_filters( 'widget_display_callback', $instance, $widget_obj, $args );

	if ( false === $instance ) {
		return;
	}

	/**
	 * Fires before rendering the requested widget.
	 *
	 * @since 3.0.0
	 *
	 * @param string $widget   The widget's class name.
	 * @param array  $instance The current widget instance's settings.
	 * @param array  $args     An array of the widget's sidebar arguments.
	 */
	do_action( 'the_widget', $widget, $instance, $args );

	$widget_obj->_set( -1 );
	$widget_obj->widget( $args, $instance );
}

Uses

Uses Description
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/functions.php: _doing_it_wrong()

Mark something as being incorrectly called.
wp-includes/functions.php: wp_parse_args()

Merges user defined arguments into defaults array.
wp-includes/plugin.php: apply_filters()

Calls the callback functions that have been added to a filter hook.
wp-includes/plugin.php: do_action()

Calls the callback functions that have been added to an action hook.
wp-includes/class-wp-widget.php: widget_display_callback

Filters the settings for a particular widget instance.
wp-includes/widgets.php: the_widget

Fires before rendering the requested widget.

Changelog

Version Description
2.8.0 Introduced.

© 2003–2021 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/the_widget