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

1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
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:

    1
    the_widget( 'WP_Widget_Categories' );

    Show widget with settings:

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

    Show widget with custom arguments:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    $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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    $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.