I am creating a theme, and I need to create and register a couple of custom widgets for my sidebar.

I need to extend the widget class (for every widget) to do this, which produces a metric ton of code. This seems to really litter my functions.php - especially since I have 5+ custom widgets at this point.

I was wondering, if there are recommended guidelines for how to best include custom widgets in your theme? I have been scouring the developers handbook, but can't find any suggestions of where it typically makes sense to store your widget class extensions?

  • Write a custom plugin: codex.wordpress.org/Writing_a_Plugin
    – shanebp
    May 12, 2020 at 18:19
  • @shanebp It is a good suggestion - and probably better in terms of inter-theme operability. However, in this case, I would like to have these widgets included in my theme if possible!
    – p01ntbr34k
    May 12, 2020 at 18:25
  • Sorry - in your theme is probably best done with a custom class and/or template-part + custom css. Find a free theme that includes a widget and examine the process. Take a look at developer.wordpress.org/themes/functionality/widgets
    – shanebp
    May 12, 2020 at 18:45

1 Answer 1


Literally, you can place the widget code anywhere inside your theme files (except template files) and include them from functions.php file.

functions.php is the only file that WordPress includes when you theme is active

There is no best practice where you put them, but that doesn't mean you should mess things up. It is best to keep each of your widget code inside a separate file.

To keep things organized, you can put each of your widget files inside any of the following folder of your theme:

  • /includes/
  • /widgets/
  • /includes/widgets/

Naming widget file:

You can only register a custom widget by extending WP_Widget class. That indicates you need to write a class for each widget. Considering this, your widget files should be named with a class prefix. Like: class-widget-one.php PHP file prefixed with a class indicates this file contain only one class.

Registering widgets:

It's better to register all of you widgets from functions.php. That's makes it easy understand how many custom widget your theme providers, and where they are located.

function wpse366458_register_widgets() {
    include( dirname( __FILE__ ) . '/widgets/class-widget-one.php' );
    register_widget( 'Theme_Widget_One' );

    include( dirname( __FILE__ ) . '/widgets/class-widget-two.php' );
    register_widget( 'Theme_Widget_Two' );
add_action( 'widgets_init', 'wpdocs_register_widgets' );

Reusing codes over multiple widgets:

Now it completely depends on your needs and taste. You can -

  • use Trait class and methods will be available inside your current widget class. ie: get_page_choices().
  • use class with static methods. ie: Prefix_Widget_Helper::get_page_choices()
  • use functions. ie: prefix_get_page_choices(), prefix_sanitize_something()
  • I would just like to say, that this is a wonderful answer. I ended up coming to a similar conclusion before you posted it, but something like this should be the honestly be a go-to guideline for theme developers, since it would also make taking over projects from other developers less of a hassle. Thank you for this!
    – p01ntbr34k
    May 12, 2020 at 20:33
  • @p01ntbr34k You are welcome. I am glad it helped.
    – Shazzad
    May 12, 2020 at 21:34

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.