the_widget() – Function | Developer.WordPress.org

Output an arbitrary widget as a template tag.

Parameters

$widgetstringrequired

The widget’s PHP class name (see class-wp-widget.php).

$instancearrayoptional

The widget’s instance settings.

Default:array()

$argsarrayoptional

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:array()

More Information

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

WP_Widget_Archives — Archives
WP_Widget_Calendar — Calendar
WP_Widget_Categories — Categories
WP_Widget_Links — Links
WP_Widget_Meta — Meta
WP_Widget_Pages — Pages
WP_Widget_Recent_Comments — Recent Comments
WP_Widget_Recent_Posts — Recent Posts
WP_Widget_RSS — RSS
WP_Widget_Search — Search (a search from)
WP_Widget_Tag_Cloud — Tag Cloud
WP_Widget_Text — Text
WP_Nav_Menu_Widget

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' ); ?>

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' ); ?>

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' ); ?>

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' ); ?>

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' ); ?>

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' );

as the heading, sort by last modified date:

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

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' ); ?>

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' ); ?>

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' ); ?>

<?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' ); ?>

<?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' ); ?>

<?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' ); ?>

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

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 );
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘the_widget’, string $widget, array $instance, array $args ): Fires before rendering the requested widget.
apply_filters( ‘widget_display_callback’, array $instance, WP_Widget $widget, array $args ): Filters the settings for a particular widget instance.

Uses	Description
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
_doing_it_wrong()`wp-includes/functions.php`	Marks something as being incorrectly called.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
do_action()`wp-includes/plugin.php`	Calls the callback functions that have been added to an action hook.

Show 3 more Show less

Used by	Description
WP_REST_Widget_Types_Controller::get_widget_preview()`wp-includes/rest-api/endpoints/class-wp-rest-widget-types-controller.php`	Returns the output of WP_Widget::widget() when called with the provided instance. Used by encode_form_data() to preview a widget.

Changelog

Version	Description
2.8.0	Introduced.

User Contributed Notes

truongwp 7 years ago

Show widget with default settings:

the_widget( 'WP_Widget_Categories' );

Show widget with settings:

the_widget( 'WP_Widget_Categories', 'dropdown=1&count=1' );

Show widget with custom arguments:

$instance = array(
	'dropdown' => 1,
	'count'    => 1,
);
$args = array(
	'before_widget' => '<div id="%1$s" class="widget %2$s">', 
	'after_widget' => '</div>',
	'before_title' => '<div class="widget-title">',
	'after_title' => '</div>'
);
the_widget( 'WP_Widget_Categories', $instance, $args );

Nico Andrade 9 years ago

Example:

$args = array(
    'before_widget' => '<div class="widget %s">', 
    'after_widget' => '</div>',
    'before_title' => '<h2 class="widget-title">',
    'after_title' => '</h2>'
    );
$instance = array(
    'title' => 'Title',
    'text' => 'Text'
    );
the_widget( 'My_Custom_Widget', $instance, $args );

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

In this article

Parameters

More Information

Archives widget

Examples

Calendar widget

Example

Categories widget

Examples

Custom HTML widget

Examples

Links widget

Examples

Meta widget

Example

Pages widget

Examples

Contents

Recent Comments widget

Example

Recent Posts widget

Example

RSS widget

Example

Search widget

Example

Example

Text widget

Example

Custom Widget

Example

Source

Hooks

Changelog

User Contributed Notes