Custom WordPress Widget Template

I had a bunch of custom widgets to create for this theme, mostly for displaying ads, and then one to display twitter/RSS followers, and one to display a tabbed widget that included popular posts, recent posts, tags and comments. Creating a custom widget is surprisingly easy, after getting the first one done, I just modified it for the others. I thought I’d share a basic template for a custom widget, which can be modified to do all sorts of things. The possibilities are endless!

The custom widget we’re creating is basically the same as the default text widget, it takes text input in the widget admin panel and displays it as a widget in your theme.

The code for our widget is going to live in a file called “widget_example.php” inside a directory called “functions” in the theme’s directory. All we have to do is reference it in functions.php.

$functions_path = TEMPLATEPATH . '/functions/';
require_once ($functions_path . 'widget_example.php');

I’ve included a lot of files from functions.php, so I stored the path in a variable.

Next we’re just going to dive right into the template, most of the important information is commented, so hopefully you can follow along:


	add_action('widgets_init', 'ex_widget_example'); 

	function ex_widget_example() { // function name matches name from add_action

	class Ex_Widget_Example extends WP_Widget {

		function Ex_Widget_Example() { // function name matches class name
			$widget_ops = array(
				'classname'=>'example-widget', // class that will be added to li element in widgeted area ul
				'description'=>'Display text from input' // description displayed in admin
			$control_ops = array(
				'width'=>200, 'height'=>250, // width of input widget in admin
				'id_base'=>'example-widget' // base of id of li element ex. id="example-widget-1"
			$this->WP_Widget('example-widget', 'Example Widget', $widget_ops, $control_ops); // "Example Widget" will be name in control panel

		function widget($args, $instance) {

				$text = $instance['text'];

				echo $before_widget;

				if ($text) echo '<p>'.$text.'</p>'; // how input text will be displayed

				echo $after_widget;

		function update( $new_instance, $old_instance ) {
			$instance = $old_instance;
			$instance['text'] = $new_instance['text'];

			return $instance;

		function form( $instance ) {

			$defaults = array('text' =>'default text');
			$instance = wp_parse_args( (array) $instance, $defaults ); ?>

				<label for="<?php echo $this->get_field_id( 'text' ); ?>">Custom Text:</label>
				<input id="<?php echo $this->get_field_id( 'text' ); ?>" name="<?php echo $this->get_field_name( 'text' ); ?>" value="<?php echo $instance['text']; ?>" style="width:100%;" />


This code outputs the following HTML when added to a widgeted area:

<li id="example-widget-3" class="widget example-widget"><p>Testing Text</p></li> 

Now to customize this widget, you basically rename all the bits that say “example” with the name of your widget, and the “Ex” prefix is where you reference your theme’s name abbreviated, to prevent clashing with functions from plugins etc.

To get the widget to do something else, you just change the variable “text” everywhere it occurs to whatever you’re going to display, for example, you might want to change it to an image, so the user would input the URL to an image, and then in the output bit, you would change it to something like

if ($image) echo '<img src="'.$image.'" />';

So there you have it, basic “copy-and-paste” template for a custom WordPress widget. Have fun!

This entry was posted in Code Snippets. Bookmark the permalink.

4 Responses to Custom WordPress Widget Template

  1. Thanks man, this widget tutorial helped me out a ton. I am working on a new theme for my site, and all the tutorials I found were out of date with 3.2. Your code worked perfect. Thanks.

  2. Margaret says:

    Thank you so much! I was hunting for how to make a custom widget in WordPress 3+ and couldn’t find anything past v2.9. Your widget template makes perfect sense and is a great starting point, plus it works perfectly. Can’t thank you enough!

  3. jason says:

    I am having one small issue…when I drag a widget into a sidebar it works as normal and opens up for input but then closes real quick.

    If I hit the expand arrow the widget will not expand or open up so I can add my text.

    I have refresh the screen for the widget to expand, enter my text then save the input.

    On WP 3.3.1

  4. “Wow, great blog post.Thanks Again. Want more.”

Leave a Reply

Your email address will not be published. Required fields are marked *