WPBeginner

Beginner's Guide for WordPress

  • Blog
    • Beginners Guide
    • News
    • Opinion
    • Showcase
    • Themes
    • Tutorials
    • WordPress Plugins
  • Start Here
    • How to Start a Blog
    • Create a Website
    • Start an Online Store
    • Best Website Builder
    • Email Marketing
    • WordPress Hosting
    • Business Name Ideas
  • Deals
    • Bluehost Coupon
    • SiteGround Coupon
    • WP Engine Coupon
    • HostGator Coupon
    • Domain.com Coupon
    • Constant Contact
    • View All Deals »
  • Glossary
  • Videos
  • Products
X
☰
Beginner's Guide for WordPress / Start your WordPress Blog in minutes
Choosing the Best
WordPress Hosting
How to Easily
Install WordPress
Recommended
WordPress Plugins
View all Guides

WPBeginner» Blog» Tutorials» How to Create a Custom WordPress Widget

How to Create a Custom WordPress Widget

Last updated on May 14th, 2020 by Editorial Staff
578 Shares
Share
Tweet
Share
Pin
Free WordPress Video Tutorials on YouTube by WPBeginner
How to Create a Custom WordPress Widget

Do you want to create your own custom widgets in WordPress? Widgets allow you to add non-content elements into a sidebar or any widget-ready area of your website.

You can use widgets to add banners, advertisements, newsletter sign up forms, and other elements to your website.

In this article, we will show you how to create a custom WordPress widget, step by step.

Creating a custom WordPress widget

Note: This tutorial is for DIY WordPress users who are learning WordPress development and coding.

What is a WordPress Widget?

WordPress widgets contain pieces of code that you can add to your website’s sidebars or widget-ready areas.

Think of them as modules that you can use to add different elements by using a simple drag and drop interface.

By default, WordPress comes with a standard set of widgets that you can use with any WordPress theme. See our beginner’s guide on how to add and use widgets in WordPress.

Adding widgets in WordPress

WordPress also allows developers to create their own custom widgets.

Many premium WordPress themes and plugins come with their own custom widgets that you can add to your sidebars.

For example, you can add a contact form, a custom login form, or a photo gallery to a sidebar without writing any code.

Having said that, let’s see how to easily create your own custom widgets in WordPress.

Video Tutorial

Subscribe to WPBeginner

If you prefer written instructions, then please continue reading.

Creating a Custom Widget in WordPress

If you are learning WordPress coding, then you will need a local development environment. You can install WordPress on your computer (Mac or Windows).

There are several ways to add your custom widget code in WordPress.

Ideally, you can create a site-specific plugin and paste your widget code there.

You can also paste the code in your theme’s functions.php file. However, it will only be available when that particular theme is active.

Another tool that you can use is the Code Snippets plugin which allows you to easily add custom code to your WordPress website.

In this tutorial, we will create a simple widget that just greets visitors. The goal here is to familiarize yourself with the WordPress widget class.

Let’s get started.

Creating a Basic WordPress Widget

WordPress comes with a built-in WordPress Widget class. Each new WordPress widget extends the WordPress widget class.

There are 18 methods mentioned in the WordPress developer’s handbook that can be used with the WP Widget class.

However, for the sake of this tutorial, we will be focusing on the following methods.

  • __construct() : This is the part where we create the widget ID, title, and description.
  • widget : This is where we define the output generated by the widget.
  • form : This part of the code is where we create the form with widget options for backend.
  • update: This is the part where we save widget options in the database.

Let’s study the following code where we have used these four methods inside the WP_Widget class.

// Creating the widget 
class wpb_widget extends WP_Widget {

// The construct part  
function __construct() {

}
 
// Creating widget front-end
public function widget( $args, $instance ) {

}
         
// Creating widget Backend 
public function form( $instance ) {

}
     
// Updating widget replacing old instances with new
public function update( $new_instance, $old_instance ) {

}

// Class wpb_widget ends here
} 

The final piece of the code is where we will actually register the widget and load it inside WordPress.

function wpb_load_widget() {
    register_widget( 'wpb_widget' );
}
add_action( 'widgets_init', 'wpb_load_widget' );

Now let’s put all of this together to create a basic WordPress widget.

You can copy and paste the following code in your custom plugin or theme’s functions.php file.


// Creating the widget 
class wpb_widget extends WP_Widget {
 
function __construct() {
parent::__construct(
 
// Base ID of your widget
'wpb_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
 
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
?>
<p>
<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 ); ?>" />
</p>
<?php 
}
     
// 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' );

After adding the code you need to head over to Appearance » Widgets page. You will notice the new WPBeginner Widget in the list of available widgets. You need to drag and drop this widget to a sidebar.

Demo widget

This widget has only one form field to fill, you can add your text and click on the Save button to store your changes.

Now you can visit your website to see it in action.

Previewing your custom widget

Now let’s study the code again.

First we registered the ‘wpb_widget’ and loaded our custom widget. After that we defined what that widget does, and how to display the widget back-end.

Lastly, we defined how to handle changes made to the widget.

Now there are a few things that you might want to ask. For example, what’s the purpose wpb_text_domain?

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.

If you are creating a custom widget for your theme, then you can replace wpb_text_domain with your theme’s text domain.

We hope this article helped you learn how to easily create a custom WordPress widget. You may also want to see our list of the most useful WordPress widgets for your site.

If you liked this article, then please subscribe to our YouTube Channel for WordPress video tutorials. You can also find us on Twitter and Facebook.

578 Shares
Share
Tweet
Share
Pin
Popular on WPBeginner Right Now!
  • How to Fix the Error Establishing a Database Connection in WordPress

    How to Fix the Error Establishing a Database Connection in WordPress

  • Checklist

    Checklist: 15 Things You MUST DO Before Changing WordPress Themes

  • Google Analytics in WordPress

    How to Install Google Analytics in WordPress for Beginners

  • Revealed: Why Building an Email List is so Important Today (6 Reasons)

    Revealed: Why Building an Email List is so Important Today (6 Reasons)

About the Editorial Staff

Editorial Staff at WPBeginner is a team of WordPress experts led by Syed Balkhi. Trusted by over 1.3 million readers worldwide.

The Ultimate WordPress Toolkit

25 Comments

Leave a Reply
  1. JP says:
    Aug 23, 2020 at 10:36 am

    this is great, simple cut and paste example was exactly what I was looking for. Thanks!

    Reply
    • WPBeginner Support says:
      Aug 24, 2020 at 3:50 pm

      You’re welcome :)

      Reply
  2. Banu says:
    Sep 11, 2019 at 1:21 am

    I have created a CRUD Plugin and i need to use it in one page could you please guide me how to use that plugin in page ?

    Reply
    • WPBeginner Support says:
      Sep 11, 2019 at 9:31 am

      It would depend on how you set up the plugin, for having it on one page you could either look to use a shortcode for front-end display or look into the options API if you wanted to display it on the admin side of a site.

      Reply
  3. Kishan says:
    Jun 28, 2019 at 11:55 pm

    How can I create more than 1 custom widget?
    And also, how can I set other fields like radio, checkbox, dropdown, text in widget?

    Reply
    • WPBeginner Support says:
      Jul 1, 2019 at 12:53 pm

      You would need to replace the wpb_widget with what you want your new widget to be called and then the code would depend on what specifically you would like to add. If you take a look at the WordPress codex you can see the different codes available.

      Reply
  4. Carmen says:
    Mar 2, 2019 at 1:20 pm

    Hello!

    Currently, I am developing a plugin and I need to create a widget to let the user add a specific functionality to his/her site.
    I copied the code for your widget in a file and saved the file in my plugin’s directory. I used add_action and do_action in my plugin’s main file to load it but it still doesn’t work. Can you help me, please?

    Thank you!

    Reply
    • WPBeginner Support says:
      Mar 4, 2019 at 1:06 pm

      Sadly, that would depend heavily on how your plugin is set up, you may want to ensure both sections of this code are being loaded for the widget to be added and displayed

      Reply
  5. Maximilian K. says:
    Jan 21, 2019 at 4:25 am

    A short question, what if i want to create widgets in where i also can place other widgets? Like empty bootstrap columns 6-3-3 e.g. and in each column i can place then widgets like image, text, latest posts etc.

    Is there a command / keyword to signalize that there is place for other widgets in this widget…

    because im kind of confused about my own created theme and how WP is working… you see im a beginner ^^

    I already placed general information like page title, make widget areas in my footer so ich can place menus, related links etc. on it. It worked.

    But now im confused how i can realize my content in wordpress as i designed it before. Maybe some keywords are helpful to read more about them.

    Reply
    • WPBeginner Support says:
      Jan 23, 2019 at 11:34 am

      That would require more customization than we go into in this article, you may need to look into how to create a sidebar for code you can use: https://www.wpbeginner.com/wp-themes/how-to-add-dynamic-widget-ready-sidebars-in-wordpress/

      Reply
  6. Lars says:
    Jan 6, 2019 at 8:03 am

    Great tutorial! Worked perfectly.

    Reply
    • WPBeginner Support says:
      Jan 8, 2019 at 10:40 am

      Glad our tutorial could help :)

      Reply
  7. Watson Anikwai says:
    Sep 13, 2018 at 7:35 am

    How do you get a custom post type field from wp database and use a widget to display on front end?

    Reply
  8. vicky says:
    Jul 19, 2018 at 10:51 am

    i can’t add two custom widgets .. the second widget is not showing up….
    what should i do???.. pls help

    Reply
  9. Ahad Bhatti says:
    Feb 21, 2018 at 9:04 am

    Really understandable and helpful. Thank you.

    Reply
  10. Belitza Gomez says:
    Jan 11, 2018 at 7:27 pm

    hello, i would like to know where i can find in available widgets the “custom menu”. it doesn’t show and i haven’t been able to add a page to the footer through this widget.

    thank you for your help!!!!

    Reply
  11. Samdoxer says:
    Nov 17, 2017 at 7:55 am

    hi, how would i show a logo in place of text. would replacing logo url with the text suffice.
    Thanks in advance.

    Reply
    • WPBeginner Support says:
      Dec 22, 2017 at 4:02 pm

      Please see your theme settings or visit Appearance » Customizer page in admin area. There you will find an option to upload your logo image.

      Reply
  12. Gary Foster says:
    Sep 29, 2017 at 12:20 pm

    Which came first the widget or the app?
    Does a widget have to be registered if so how Please?
    How do you best protect your idea of a widget or app?
    Thanks all

    Reply
  13. shelley says:
    Aug 18, 2017 at 11:22 am

    These instructions worked beautifully for creating my custom widget. I cannot, however, figure out how to change the font size to 60px. I did manage to add CSS to Divi theme options that centered the text and added a line border. But how do I change the styling of the font please? Adding “font-size:60px” does not work. I want the font to be large, like a tagline running across the page. Thanks.

    Reply
  14. Ahmad Farhan says:
    Jun 25, 2017 at 12:58 am

    Very helpfull. tankyou :)

    Reply
  15. Eyad says:
    Jun 17, 2017 at 4:47 am

    Thanks so much for your tutorials

    Reply
  16. Luigi Briganti says:
    Jun 12, 2017 at 7:52 am

    Hi! I hope you can help me.

    I’ve created a custom post type that show the timetable for a shop. Of course, you can create as much timetables as you want, but my necessity is to show a given timetable in the sidebar of the website.

    For this purpose I made a widget that loop the timetable posts showing only 1 (namely the first one, since I ordered in ASC order). This is a temporary solution, just to see if the widget works and it does, actually.

    What I really want to do is to show in the backend a dropdown list of all posts belonging to “timetable” post type so that I can choose the one I need when I need it and show it in the frontend. How can I do this?

    Thanks if you may/want to help.

    Reply
  17. Anees Ijaz says:
    Jun 9, 2017 at 12:06 pm

    Thanks Man for saving my time ..

    Reply
  18. Kevin says:
    Jun 8, 2017 at 10:37 am

    I love this post, helped me often a lot! Thanks!

    Reply

Leave a Reply Cancel reply

Thanks for choosing to leave a comment. Please keep in mind that all comments are moderated according to our comment policy, and your email address will NOT be published. Please Do NOT use keywords in the name field. Let's have a personal and meaningful conversation.

Over 1,320,000+ Readers

Get fresh content from WPBeginner

Featured WordPress Plugin
WP Mail SMTP logo
WP Mail SMTP
Fix WordPress email delivery issues. #1 SMTP plugin. Learn More »
How to Start a Blog How to Start a Blog
I need help with ...
Starting a
Blog
WordPress
Performance
WordPress
Security
WordPress
SEO
WordPress
Errors
Building an
Online Store
Useful WordPress Guides
    • 7 Best WordPress Backup Plugins Compared (Pros and Cons)
    • How to Fix the Error Establishing a Database Connection in WordPress
    • Why You Need a CDN for your WordPress Blog? [Infographic]
    • 30 Legit Ways to Make Money Online Blogging with WordPress
    • Self Hosted WordPress.org vs. Free WordPress.com [Infograph]
    • Free Recording: WordPress Workshop for Beginners
    • 24 Must Have WordPress Plugins for Business Websites
    • How to Properly Move Your Blog from WordPress.com to WordPress.org
    • 5 Best Contact Form Plugins for WordPress Compared
    • Which is the Best WordPress Popup Plugin? (Comparison)
    • Best WooCommerce Hosting in 2020 (Comparison)
    • How to Fix the Internal Server Error in WordPress
    • How to Install WordPress - Complete WordPress Installation Tutorial
    • Why You Should Start Building an Email List Right Away
    • How to Properly Move WordPress to a New Domain Without Losing SEO
    • How to Choose the Best WordPress Hosting for Your Website
    • How to Choose the Best Blogging Platform (Comparison)
    • WordPress Tutorials - 200+ Step by Step WordPress Tutorials
    • 5 Best WordPress Ecommerce Plugins Compared
    • 5 Best WordPress Membership Plugins (Compared)
    • 7 Best Email Marketing Services for Small Business (2020)
    • How to Choose the Best Domain Registrar (Compared)
    • The Truth About Shared WordPress Web Hosting
    • When Do You Really Need Managed WordPress Hosting?
    • 5 Best Drag and Drop WordPress Page Builders Compared
    • How to Switch from Blogger to WordPress without Losing Google Rankings
    • How to Properly Switch From Wix to WordPress (Step by Step)
    • How to Properly Move from Weebly to WordPress (Step by Step)
    • Do You Really Need a VPS? Best WordPress VPS Hosting Compared
    • How to Properly Move from Squarespace to WordPress
    • How to Register a Domain Name (+ tip to get it for FREE)
    • HostGator Review - An Honest Look at Speed & Uptime (2020)
    • SiteGround Reviews from 4196 Users & Our Experts (2020)
    • Bluehost Review from Real Users + Performance Stats (2020)
    • How Much Does It Really Cost to Build a WordPress Website?
    • How to Create an Email Newsletter the RIGHT WAY (Step by Step)
    • Free Business Name Generator (A.I Powered)
    • How to Create a Free Business Email Address in 5 Minutes (Step by Step)
    • How to Install Google Analytics in WordPress for Beginners
    • How to Move WordPress to a New Host or Server With No Downtime
    • Why is WordPress Free? What are the Costs? What is the Catch?
    • How to Make a Website in 2020 – Step by Step Guide
Deals & Coupons (view all)
SendinBlue Coupon Code
Sendinblue Coupon
Get Sendinblue, a powerful marketing automation toolkit for small businesses, for FREE.
StackPath's logo
StackPath (MaxCDN) Coupon
Get StackPath CDN for just $10/month! It's the same service we use to make our site super fast.
Featured In
About WPBeginner®

WPBeginner is a free WordPress resource site for Beginners. WPBeginner was founded in July 2009 by Syed Balkhi. The main goal of this site is to provide quality tips, tricks, hacks, and other WordPress resources that allows WordPress beginners to improve their site(s).
Join our team: We are Hiring!

Site Links
  • About Us
  • Contact Us
  • FTC Disclosure
  • Privacy Policy
  • Terms of Service
  • Free Blog Setup
  • Free Business Tools
Our Sites
  • OptinMonster
  • MonsterInsights
  • WPForms
  • SeedProd
  • Nameboy
  • RafflePress
  • Smash Balloon

Copyright © 2009 - 2021 WPBeginner LLC. All Rights Reserved. WPBeginner® is a registered trademark.

Managed by Awesome Motive | WordPress hosting by SiteGround | WordPress CDN by MaxCDN | WordPress Security by Sucuri.