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

Output an arbitrary widget as a template tag.

Contents

Description Description

Parameters 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()

Top ↑

Source 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 ] ) ) {
		/* translators: %s: register_widget() */
		_doing_it_wrong( __FUNCTION__, sprintf( __( '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 );

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

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
2.8.0 Introduced.

Top ↑

Top ↑

Uses Uses

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

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

Execute functions hooked on a specific action hook.
wp-includes/widgets.php: the_widget

Fires before rendering the requested widget.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by truongwp —

    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 );
  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Nico Andrade —

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

You must log in before being able to contribute a note or feedback.