WordPress.org

Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/the widget

This page is marked as incomplete. You can help Codex by expanding it.

Description

This template tag displays an arbitrary widget outside of a sidebar. It can be used anywhere in templates.

Usage

 <?php the_widget$widget$instance$args ); ?> 

Parameters

$widget
(string) (required) The widget's PHP class name. The classes for the widgets included with WordPress are:
Default: None
$instance
(array|string) (optional) The widget's instance settings. Either an array or query-style string. See each widget below for examples.
Default: array()
$args
(array|string) (optional) The widget's sidebar args. Either an array or query-style string. If empty, it defaults to:
before_widget
(string) the text or HTML befor the widget.
Default: <div class="widget {widget's classname}">
after_widget
(string) the text or HTML after the widget.
Default: </div>
before_title
(string) the text or HTML before the widget's title.
Default: <h2 class="widgettitle">
after_title
(string) the text or HTML after the widget's title.
Default: </h2>
Default: array()

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

Links widget

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

Notes

  • Uses: global $wp_widget_factory - To retrieve the widget object.
  • Uses: do_action() - Calls 'the_widget' with $widget, $instance and $args.

Change Log

Source File

the_widget() is located in wp-includes/widgets.php

Resources

Related

Widgets: is_active_widget(), the_widget(), register_widget(), unregister_widget(), wp_register_widget_control(), wp_unregister_widget_control(), wp_convert_widget_settings(), wp_get_widget_defaults(), wp_widget_description()

See also index of Function Reference and index of Template Tags.