## Widgets API Documentation

This page contains the technical documentation of the WordPress Widgets API (Application Programming Interface). The intended audience for this information includes WordPress theme authors, plug-in authors and anyone who would like to write a stand-alone widget. This document assumes a basic understanding of PHP scripting.

Tutorials are also available for widgetizing your [themes](https://automattic.com/code/widgets/themes/) and [plug-ins](https://automattic.com/code/widgets/plugins/).

### Theme functions

These functions are used to make a theme work with widgets:

void **register_sidebars** ( 
- int count 
- mixed args 
) Registers one or more sidebars to be used in the current theme. Most themes have only one sidebar. For this reason, the `count` parameter is optional and defaults to one. The `args` parameter will be passed to **register_sidebar** and follows its format, with the exception of the `name`, which is treated with sprintf() to insert or append a unique number to each sidebar if `count` is plural. For example, the following line will create sidebars name “Foobar 1” and “Foobar 2”:

```
register_sidebars(2, array('name'=>'Foobar %d'));
```

void **register_sidebar** ( 
- mixed args 
) The optional `args` parameter is an associative array that will be passed as a first argument to every active widget callback. (If a string is passed instead of an array, it will be passed through parse_str() to generate an associative array.) The basic use for these arguments is to pass theme-specific HTML tags to wrap the widget and its title. Here are the default values:

```
'before_widget' => '<li id="%1$s" class="widget %2$s">',
'after_widget' => "</li>n",
'before_title' => '<h2 class="widgettitle">',
'after_title' => "</h2>n"
```

The only times you might need to call this function instead of **register_sidebars** are when you want to give unique names to sidebars, such as “Right Sidebar” and “Left Sidebar”, or when they should be marked up differently. The names only appear in the admin interface but they are also used as an index for saving the sidebar arrangements. Consequently, sidebars can have their arrangements reused and overwritten when another theme is chosen that uses the same names. The default before/after values are intended for themes that generate a sidebar marked up as a list with `h2` titles. This is the convention we recommend for all themes and any theme built in this way can simply register sidebars without worrying about the before/after tags. If, for some compelling reason, a theme cannot be marked up in this way, these tags must be specified when registering sidebars. It is recommended to copy the `id` and `class` attributes verbatim so that an internal sprintf call can work and CSS styles can be applied to individual widgets. bool **dynamic_sidebar** ( 
- mixed sidebar 
) The template tag. This function calls each of the active widget callbacks in order, which prints the markup for the sidebar. If you have more than one sidebar, you should give this function the name or number of the sidebar you want to print. This function returns true on success and false on failure. The return value should be used to determine whether to display a static sidebar. This ensures that your theme will look good even when the Widgets plug-in is not active. Along with a sanity test to prevent fatal errors, here is the recommended use of this function:

```
<ul id="sidebar">
<?php if ( !function_exists('dynamic_sidebar')
|| !dynamic_sidebar() ) : ?>
<li>{static sidebar item 1}</li>
<li>{static sidebar item 2}</li>
<?php endif; ?>
</ul>
```

If your sidebars were registered by number, they should be retrieved by number. If they had names when you registered them, use their names to retrieve them.

### Widget registration functions

Widgets can be defined in plug-ins or in a theme’s functions.php file. Each widget consists of at least one output function which is registered as a named callback with the following functions:

void **register_sidebar_widget** ( 
- string name, 
- callback 
- string classname 
) Registers `callback` as a widget output function with unique index `name`. This causes a draggable object containing `name` to appear in the admin interface. A basic widget is simply a function that prints some HTML. To get a widget included in the widgets palette, you must register it via this function. It is possible for theme authors to define replacement widgets within functions.php. Replace an existing widget by registering its `name` with a new `callback`. An empty `callback` will unregister a widget. Because each widget has a unique name and a non-unique callback, the default markup before a widget looks like this:

```
<li id="{name}" class="{callback}">{callback output}</li>
```

When you register a widget you may pass a custom classname to replace `callback`. This is most useful for object-oriented widgets whose callbacks are passed as arrays.

void **unregister_sidebar_widget** ( 
- string name 
) Makes a previously available widget unavailable. This is most commonly used within a theme’s functions.php to disable a widget that does not work well in that theme’s sidebar.

void **register_widget_control** ( 
- string name, 
- callback 
- int width 
- int height 
) Adds the output of `callback` to the admin interface as an inline popup. The popup is a child of the main form so it must not include <form> tags or `submit` buttons. It should include form inputs with very specific names and id’s. The form data should also be handled within `callback` as its first action, but advanced widgets may have good reasons to differ from this model.

void **unregister_widget_control** ( 
- string name 
) Removes a widget’s admin callback.