Beginner's Guide for WordPress - Start your WordPress Blog in minutes.
Choosing the Best
WordPress Hosting
How to Easily
Install WordPress
WordPress Plugins
View all Guides

How to Create a Custom WordPress Widget

Last updated on by
Special WordPress Hosting offer for WPBeginner Readers
How to Create a Custom WordPress Widget

WordPress widgets make it super easy for users to simply drag and drop elements into their site. There are many WordPress themes and plugins that use widgets to allow users to create their own layouts. There are even plugins to improve widget management. In this article, we will show you how to create your own custom WordPress widget.

What is a WordPress Widget?

WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. The great thing about widgets is that you can drag and drop them into your sidebars or any widget ready areas of your website. This allows great flexibility to plugin and theme developers. They can add functionality into their products and let users decide when and where to use that functionality without messing with code. Similarly, as a user you can also create your own widgets in a site-specific plugin, so that you can drag and drop them into any theme you are using.

Creating a Custom WordPress Widget

Creating a Widget in WordPress

Before we get started, it would be best if you create a site-specific plugin where you will be pasting widget code. You can also paste it in your theme’s functions.php file but a site-specific plugin is better.

In this tutorial, we will create a simple widget that just greets visitors. Take a look at this code and then paste it in your site-specific plugin to see it in action.

// Creating the widget 
class wpb_widget extends WP_Widget {

function __construct() {
// Base ID of your widget

// Widget name will appear in UI
__('WPBeginner Widget', 'wpb_widget_domain'), 

// Widget description
array( 'description' => __( 'Sample widget based on WPBeginner Tutorial', 'wpb_widget_domain' ), ) 

// Creating widget front-end
// This is where the action happens
public function widget( $args, $instance ) {
$title = apply_filters( 'widget_title', $instance['title'] );
// before and after widget arguments are defined by themes
echo $args['before_widget'];
if ( ! empty( $title ) )
echo $args['before_title'] . $title . $args['after_title'];

// This is where you run the code and display the output
echo __( 'Hello, World!', 'wpb_widget_domain' );
echo $args['after_widget'];
// Widget Backend 
public function form( $instance ) {
if ( isset( $instance[ 'title' ] ) ) {
$title = $instance[ 'title' ];
else {
$title = __( 'New title', 'wpb_widget_domain' );
// Widget admin form
<label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label> 
<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" />
// Updating widget replacing old instances with new
public function update( $new_instance, $old_instance ) {
$instance = array();
$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
return $instance;
} // Class wpb_widget ends here

// Register and load the widget
function wpb_load_widget() {
	register_widget( 'wpb_widget' );
add_action( 'widgets_init', 'wpb_load_widget' );

Now go to Appearance » Widgets, drag and drop WPBeginner Widget in your sidebar to see this custom widget in action.

Simple wasn’t it? First we created a custom widget. Then we defined what that widget does and how to display the widget back-end. Then we defined how to handle changes made to widget. Lastly, we registered and loaded the widget.

Now there are a few things that you might want to ask. For example, what wpb_text_domain does? WordPress uses gettext to handle translation and localization. This wpb_text_domain and __e tells gettext to make a string available for translation. See how you can find translation ready WordPress themes.

We hope this tutorial helped you learn how to create a custom WordPress widget. Let us know what widgets you are creating, by leaving a comment below.

Editorial Staff at WPBeginner is a team of WordPress experts led by Syed Balkhi. Page maintained by Syed Balkhi.

WPBeginner's Video Icon
Our HD-Quality tutorial videos for WordPress Beginners will teach you how to use WordPress to create and manage your own website in about an hour. Get started now »


  1. Rashid says:

    This website showing a pop up when leaving. Please tell me this plugin. i want feedback from visitors when they are leaving

  2. Id abdou says:

    thnxx a lot for this tuto .. its very helpful for as a beginner

  3. Deeba says:

    Hi everyone,

    I created a site specific plugin and paste this code into this. This widget shown in my Appearance->widgets. but, I can not get into my front-end. I don’t know why this happens like this. Can you please anyone help me

    Thanks in Advance.

  4. Elisa says:

    My plugin is activated, but the widget doesn’t show up in Appearance -> Widgets :S
    I followed this tutorial (nice one, btw) but I can’t get this solved

  5. Fernando says:

    Hello do you know how to add javascript support to that widget?


    • Eugene Qilo says:

      You are forgetting to mention a very important step…. You have to go to plugins and activate your plugin in order for the widget to show

  6. Laura Sage says:

    I might add one other issue I’m having:

    Everything appears correctly in the widget admin area. But when I click “save” on the choices made, everything switches back to the defaults. However, when I refresh the page and go to that widget again, the choices all appear correctly. So it seems like it’s saving things, but not immediately displaying them as saved correctly. Any idea what could be causing that?

  7. Kalou says:

    Hello, great tuto

    I followed it, everything is fine but my Widget doesn’t appear in the webpage and is greyed out in the admin panel

    What have I done wrong? Any idea?

  8. sumon says:

    This is really helpful to me and how can define the new widget area in my theme to show the new widget ? If any one could solve this please give me your feedback. Thanks

  9. Abdul Shomad says:

    This instruction rocks, I created my own first widget, although the shortcode I call not my own :D

    Got mistake that the bottom of widget keep going to next widget without separator then I added those ‘after_widget’ echo, and voila!

    Thanks for the tutorials, I’m not even a programmer :D

    • WPBeginner Support says:

      Glad you found it useful.

      • Abdul Shomad says:

        I just realize this widget post last updated on 2013, a little bit different than WP guide

        Is this WPB widget still okay, I mean secure and following WP guideline? or should follow directly on WP Codex?

  10. Matěj Škarka says:

    I succesfully added widget that I created by your way.
    But can you help me how to create more then one widget? What do I have to edit? Because when I try to use this code more then once then it doesn’t work.


    • Abdul Shomad says:

      You have to change it’s naming, I mean change anything that contain likes ‘wpb_widget’
      Create your own widget name, new fucntion name, new base ID, etc
      Follow the instruction comment.

  11. Sylvia Liney says:

    Sorry, but that made no sense to me. I have been blundering around making a blog, & not understanding anything I was doing. I think it’s too technical for me. Is there any articles I can read that might light my way? For old people….I think I got the very very basic things, but the only experience I have had with widgets was ‘copy-paste’ a code & add it into a little box on a forum….and it was sooo easy & it worked!
    So, I am old, female & have had no formal education in this field. If I could understand why I was doing something, maybe I could do it.
    Thanks for reading…any help would be much appreciated. Step by Step, please!
    I am using WIN XP SP 3.0 32 bit on a desktop computer
    Peace and Love
    Sylvia x

  12. Ryan G. Wilson says:

    Hello. Great tutorial, thank you. I’ve added a content area to my widget where I want the user to input HTML (such as links and break tags). Currently those are being displayed literally – how to I display as functional HTML code (e.g. links work correctly, bold text in tag would be bold, tags add a hard return, etc)?

  13. Ismail Tofiq says:

    Good articles for beginners. Really helpful !

  14. Tushar Sharma says:

    Thankyou. With this article and website’s help, I was able to make my own Widget and Widget area, and display them with shortcodes. This day has been great!

  15. vinit says:

    how to add coustom widgets in footer accodid to theme

  16. Blair2004 says:

    Within update method, the parameter “old_instance” is not used… is it normal ?

  17. Yasir Ghafoor says:

    its so helpfull for me

  18. Craig R says:

    Excellent tutorial – thanks

    I have modified the basic example and created a widget to take 3 inputs for a modal window, (title, content, button text) which works !!

    If I try and add multiple instances of the widget to my widget area, I get the same modal window-so only the first instance is recognised.

    How can I create a widget that can be configured for multiple instances ?

  19. Shashi says:

    I see that the widget loads on the front end, only when the administrator is logged in. But it does not appear for non-logged in users. Is there a way to display the widget for all users ?

  20. Shashi says:

    Thanks for providing this simple tutorial. I am able to setup a custom form as a widget in my wordpress site.

    • vannat says:

      hello sir, i also want to create a form as a widget in my wordpress site too. so could you please give me some tip to do that. And would you mind uploading your sample here.

  21. tkjeldsen says:

    hi is it posible to add HTML5 API in to a widget

  22. Akhil says:

    Hi I want to create a widget for home page only. It is not in side bar, its will be static home page and 3 boxes under the banner, I need to display widget in the boxes with learn more link. How I can do it?

  23. Dave Levy says:

    Works for me too, if one wants to use the include statement in the plugin file, then the code above needs to be surrounded by

  24. shree says:

    hey i want to add widgets to the center page??im confuse

  25. JKeefer says:

    Worked great, thank you!

  26. Chris says:

    I’m sure there’s a way to do this but I’m not entirely clear on how to go about it. I’ve done this tutorial and made a widget. Everything works fine. I’ve also extended this widget in that now it has image upload support through WordPress’ media upload functionality. And a way to add hyperlinks around uploaded images. What I thought would be nice is to implement jQuery’s drag and drop functionality so the display of the available fields in this widget could be controlled by the user. I’ve seen other plugins with this kind of functionality, but like I said I have no idea how to implement this. I know the jQuery UI library is at work here if that makes it easier to understand what I’m trying to do. Thanks much for the tutorial.

  27. WPBeginner Staff says:

    Yes Yatko it makes sense, however we are trying to just get our users started. We will try to cover more advanced topics in some future article.

  28. yatko says:

    Thank you for the great explanation it really helps in creating a widget in a very easy and proper way. I have added a few more details (will share the code) such as register/enqueue styles and scripts or jQuery, that may help beginners. One thing would be very helpful if you would include in the article and sample code, one or two extra options and their admin-form-values. That would help most people with adding their desired widget options and settings. Does this make sense? Thanks again!

  29. M J says:

    I have created my widget and it’s saving all the info I put in, the issue I have is that I have a title for the menu I select but I can’t figure out how to display that title on the site side. It’s a secondary title that is displayed above the menu not the widget title

  30. Folthan says:

    Ahh thanks for this tutorial, together with the site specific plugin tutorial it helped me make a simple widget that echo’s form information to the homepage. Now I am off editing it all in css :).

  31. Jeff says:

    HI, thank u so much. Really easy explained. Im a WP and PHP beginner. Can u tell me what i need to do to add a Textbox after the Title ??



  32. Jessi Lee says:

    This worked great for me! Thank you SO much for sharing :)
    I was trying to add Doubleclick For Publisher inside a WordPress widget and this method worked perfectly. I just echoed the javascript and div tags where your ‘Hello World’ was and viola!


  33. Sharul Hafiz says:

    I’ve got this error in debug mode

    Notice: Undefined index: before_title in …

    How to fix this?

  34. Hunk says:

    I did as you said and succeed, but it is just a text widget, useless, how can I make a complicated widget with your method?

    • WPBeginner Support says:

      Great, the purpose of the tutorial is to teach the basics of how to create a custom widget. After that, you can try your hands on creating a jQuery Tabber Widget. Also, another way to learn is to study the source of other plugins. WordPress plugin directory has thousands of plugins tagged widgets. You can download them and learn by trying to modify those plugins.

  35. Eric says:

    Thank you! Do you have a minute to help me troubleshoot something? We can continue via email if you’d like. The code works wonderfully, except that it’s displaying “000” before my output.

  36. Mike Oberdick says:

    Excellent tutorial…I like that you left it up to the user to tweak and learn from what you presented. I’ll be creating a widget that only displays posts from a certain category. Thanks for the great info!

  37. Luke Carrier says:

    The formatting of this code is extremely poor for a beginner’s tutorial. Could you at least correctly indent it so as to encourage best practice?

  38. Jassi Bacha says:

    Pasted this code and tweaked it around, had my own widget working in under 20 minutes. The commented documentation was perfect, you’re a lifesaver!

  39. Maddy says:

    Thankz for easy, simple code clearification…

  40. HiddenLife says:

    i paste your code into my functions.php file and it worked correctly . thanks a lot !

  41. XCOP91 says:

    Yup, this worked for me thank you very much. Great Stuff.

  42. Mas says:

    I just pasted the code into my theme , functions.php , but no widgets added !
    how should I correct it ?

  43. faizan ali says:

    Hey Guys

    I’m very new to wordpress, i want to make a custom Widget like above so please kindly let me know in which page should i paste the above widget code?


  44. Eoghan says:

    Ah yes finally! I can copy and paste and see it working!
    That’s the easiest way for me to break it down and understand how to use the component.

    Thank you very much!

  45. adolf witzeling says:

    Enjoyed reading this great tutorial.Very easy to follow, even for beginners like me.

  46. Ajay M says:

    Don’t you think the title is bit misleading as it does not cover the how to part of the title pretty well.

    • WPBeginner Support says:

      We tried to cover the how to part in the code by commenting. We wanted users to study the code. Let us know which part you would like us to explain further?

  47. Muhammad Khalil Janjua says:

    Thanks for this beautiful and simple I really like it.

Add a Comment

We're glad you have chosen to leave a comment. Please keep in mind that all comments are moderated according to our comment policy, and all links are nofollow. Do NOT use keywords in the name field. Let's have a personal and meaningful conversation.