the_widget() │ WP 2.8.0

Outputs a ready-made widget directly in the theme template, forming a complete HTML block taking into account the widget settings and wrappers.

Allows you to insert any registered widget (both built-in and custom) into the desired place in the template, bypassing the sidebar areas. At the same time, you can pass your own instance settings and replace the standard tag wrappers so that the widget fits into the theme layout.

The widget must be registered in advance via register_widget(), otherwise the function will generate a message _doing_it_wrong().

Before outputting, the event the_widget is executed, and through the filter widget_display_callback, you can change the instance parameters before rendering.

The function outputs the content immediately and does not return data; use buffering ob_start() / ob_get_clean() if you need the HTML code as a string:

<?php
ob_start();
the_widget( 'WP_Widget_Search', [ 'title' => 'Search the site' ] );
$widget_html = ob_get_clean();

echo $widget_html;
Hooks from the function

Returns

null. Nothing. Outputs the HTML code of the widget to the screen.

Usage

the_widget( $widget, $instance, $args );
$widget(string) (required)

The name of the PHP class responsible for the widget. see /wp-includes/default-widgets.php.

Widgtes out of the box:

WP_Widget_Pages
WP_Widget_Links
WP_Widget_Search
WP_Widget_Archives
WP_Widget_Media
WP_Widget_Media_Audio
WP_Widget_Media_Image
WP_Widget_Media_Video
WP_Widget_Media_Gallery
WP_Widget_Meta
WP_Widget_Calendar
WP_Widget_Text
WP_Widget_Categories
WP_Widget_Recent_Posts
WP_Widget_Recent_Comments
WP_Widget_RSS
WP_Widget_Tag_Cloud
WP_Nav_Menu_Widget
WP_Widget_Custom_HTML
WP_Widget_Block

Detailed description of each widget can be found below.

$instance(array/string)

Widget parameters (instance class settings).

You can specify: an array array('dropdown'=>'1') or a query string: 'dropdown=1&count=1'.

What parameters each widget has can be found below. Or go to the WP admin panel Appearance > Widgets, activate the desired widget and see what parameters it has. To find out the specific name of a parameter, look at the last value of the name attribute of the widget field, for example, for the "tag cloud" widget, the field "title" is equal to name="widget-tag_cloud[2][title]" - which means the setting will be - title.

oblako

Default: array()

$args(array)

Array of parameters for changing the widget display. It can be:

Default: array()

  • before_widget(string)
    HTML that will be added before the widget code.
    Must contain %s — it will be replaced with the widget CSS class.

    Default: <div class="widget %s">, where %s is the widget class.

  • after_widget(string)
    HTML that will be added after the widget code.
    Default: </div>

  • before_title(string)
    HTML that will be added before the widget title code.
    Default: <h2 class="widgettitle">

  • after_title(string)
    HTML that will be added after the widget title code.
    Default: </h2>

Examples

1

#1 Demo

Show widget with default settings:

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

Show settings widget:

<?php the_widget( 'WP_Widget_Categories', 'dropdown=1&count=1' ); ?>

Show widget with custom parameters:

<?php 
$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 );
?>

Basic WordPress Widgets

Contents:

WP_Widget_Archives – archives

the_widget( 'WP_Widget_Archives', $instance, $args );
  • Widget code
  • classname: widget_archive
  • id_base: archives

Widget parameters - possible fields of $instance:

title(string)
Widget title.
Default: __('Archives')
count(int)
How many posts to display for each archive. The show_post_count parameter for the wp_get_archives() function.
Default: 0 (hide)
dropdown(boolean)
1 - as a dropdown list. 0 - as a ul list.
Default: 0 (ul list)

Examples:

Basic output:

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

Dropdown list:

<?php the_widget( 'WP_Widget_Archives', 'dropdown=1' ); ?>

WP_Widget_Calendar – calendar

<?php the_widget( 'WP_Widget_Calendar', $instance, $args ); ?>
  • Widget code
  • classname: widget_calendar
  • id_base: calendar

Widget parameters - possible fields of $instance:

title(string)
Widget title
Default: ''

Examples:

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

WP_Widget_Categories – categories

<?php the_widget( 'WP_Widget_Categories', $instance, $args ); ?>
  • Widget code
  • classname: widget_categories
  • id_base: categories

Widget parameters - possible fields of $instance:

title(string)
Widget title.
Default: __( 'Categories' )
count(int)
Number of posts in each category. The show_count parameter in the functions: wp_dropdown_categories() or wp_list_categories().
Default: 0 (hide)
hierarchical(boolean)
1 - Tree-like output: child and parent categories. 0 - one level for all.
Default: 0 (flat output)
dropdown(boolean)
1 - as a dropdown list. 0 - as a ul list.
Default: 0 (ul list)

Examples:

Basic usage:

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

Dropdown list with the number of posts in categories:

<?php the_widget( 'WP_Widget_Categories', 'dropdown=1&count=1' ); ?>

WP_Widget_Meta – login/logout and meta data

Outputs useful links: login/logout, admin panel, feeds, WordPress links.

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

Widget parameters - possible fields of $instance:

title(string)
Widget title.
Default: __('Meta')

Examples:

Let's output the widget:

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

WP_Widget_Pages – static pages

Outputs a list of pages.

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

Widget parameters - possible fields of $instance:

title(string)
Widget title.
Default: __('Pages')
sortby(string)
Column for sorting. The sort_column parameter of the wp_list_pages() function.
Default: 'menu_order'
exclude(string/array)
ID of posts to exclude from the list. Comma-separated or in an array.
Default: ''

Examples:

Let's output the list of pages:

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

Let's wrap the widget title in an h3 tag and sort the pages by modification date:

<?php the_widget('WP_Widget_Pages', 'title=Modified Pages&sortby=post_modified', 'before_title=<h3>&after_title=</h3>'); ?>

WP_Widget_Recent_Comments – recent comments

<?php the_widget( 'WP_Widget_Recent_Comments', $instance, $args ); ?>
  • Widget code
  • classname: widget_recent_comments
  • id_base: recent-comments

Widget parameters - possible fields of $instance:

title(string)
Widget title.
Default: __('Recent Comments')
number(int)
Number of comments to display. Maximum 15.
Default: 5

Examples:

Let's output the recent comments:

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

WP_Widget_Recent_Posts – recent posts

<?php the_widget( 'WP_Widget_Recent_Posts', $instance, $args ); ?>
  • Widget code
  • classname: widget_recent_entries
  • id_base: recent-entries

Widget parameters - possible fields of $instance:

title(string)
Widget title.
Default: __('Recent Posts')
number(int)
Number of posts to display. Maximum 15.
Default: 5

Examples:

Let's output the recent posts:

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

WP_Widget_RSS – RSS

Outputs a list of items from the specified URL for RSS or Atom feed.

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

Widget parameters - possible fields of $instance:

title(string)
Widget title.
Default: taken from the specified URL
url(string) (required)
URL for the RSS or Atom feed.
items(int)
Number of links to display.
Default: all from the feed
show_summary(boolean)
Display a short description under the links?
Default: false
show_author(boolean)
Display the post author?
Default: false
show_date(boolean)
Display the publication date?
Default: false

Examples:

Let's output the posts from this site:

the_widget( 'WP_Widget_RSS', array(
	'feed' => 'http://wp-kama.ru/feed',
	'items' => 5,
	'show_summary' => true
) );
<?php the_widget( 'WP_Widget_Search', $instance, $args ); ?>

Widget parameters - possible fields of $instance:

title(string)
Title of the search form.
Default: null

Examples:

Let's output the search form:

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

WP_Widget_Tag_Cloud – tag cloud

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

Widget parameters - possible fields of $instance:

title(string)
Widget title.
Default: __('Tags')
taxonomy(string)
The name of the taxonomy from which the cloud will be built.
Default: post_tag

Examples:

Let's output the tag cloud:

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

WP_Widget_Text – custom text

Outputs any text. HTML tags can be used in the text.

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

Widget parameters - possible fields of $instance:

title(string)
Widget title.
Default: null (no title)
text(string)
Text to be displayed in the widget. HTML tags can be used.
Default: ''
filter(string)
If specified, the output will be processed by the wpautop() function.
Default: ''

Examples:

Let's output custom text:

the_widget( 'WP_Widget_Text', 'title=My Text &text=This is <b>text</b>' );

/* Will output:
<div class="widget widget_text">
	<h2 class="widgettitle">My Text </h2>
	<div class="textwidget">This is <b>text</b></div>
</div>
*/

Outputs links from the specified menu. Takes into account the nesting and order of elements.

<?php the_widget( 'WP_Nav_Menu_Widget', $instance, $args ); ?>
  • Widget code
  • classname: nav_menu_widget
  • id_base: nav_menu

Widget parameters - possible fields of $instance:

title(string)
Widget title.
Default: null
nav_menu(string/int) (required)
ID of the menu to be displayed. The menu ID can be found in the admin panel, in the menu settings - look in the URL (the ID is visible there) or take the menu name itself as the ID.

Examples:

Let's output menu 2 and "My Menu":

the_widget( 'WP_Nav_Menu_Widget', array('nav_menu' => 2) );

the_widget( 'WP_Nav_Menu_Widget', array('nav_menu' => 'My Menu') );

To output a menu in WordPress, there is a special function: wp_nav_menu()

Custom Widget

Outputs any widget. Let its class be called "My_Custom_Widget".

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

  • Class name: WIDGET CLASS NAME

  • Parameters (settings): arbitrary

  • Arguments: arbitrary

Examples:

The widget is registered in the code like this. For more information on registering a widget, see the examples of register_widget():

class My_Custom_Widget extends WP_Widget{
	// your code
}

And then it is output like this:

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

Notes

  • Global. WP_Widget_Factory. $wp_widget_factory

Changelog

Since 2.8.0 Introduced.

the_widget() code WP 7.0

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

Sidebar (widgets)

Widgets (sidebars)