Software, Development, and WordPress

Programmatically Deactivate WordPress Widgets

If you’re in the business of building themes for fun, for clients, or for purchase within a marketplace or your own store, then there’s a chance that there’s some type of functionality that’s unique to your theme that should be activated whenever the theme is activated.

In my experience, this is something that’s typically unique to niché WordPress themes because they tend to have specific features, customizations, and so on that are relevant to their theme.

Case in point: Let’s say that you’re working on a niché theme that has a number of widgetized areas, but also has very specific widgets for said areas. That is, upon theme activation, you want to make sure that each widgetized area is clear so not to bust up the layout.

In other words, you need to programmatically deactivate WordPress widgets whenever the theme is activated so that the layout of the theme looks as it should when the user activates it.

How To Deactivate WordPress Widgets Programmatically

There are a number of good articles that provide ways to unregister a widget in WordPress (such as this Codex article), but there’s a different in unregistering a widget and deactivating a widget:

Unregistering a widget completely removes it as an option to drop into a widgetized area; deactivating a widget removes all activate widgets from the sidebars but still makes them available for use.

Deactivating widgets is actually really simple (especially if you’re looking to do it on theme activation):

Here’s what’s happening in the code above:

  1. First, check to see if the `acme_cleared_widget` flag exists and is set to `true`. If not, then we need to update the options; if so, then we won’t do anything.
  2. If the flag has not been set, then we’ll set the `sidebars_widgets` option equal to an array and then set the `acme_cleared_widget` value to `true`.

Easy enough, right?

Simply put, the activate widgets are kept in a serialized array in the sidebars_widgets option in the options table. By serializing an empty array, we’re completely removing whatever was stored before (more on this at the end of the post).

The reason that this is wrapped in a conditional and has the acme_cleared_widgets option is so that we’re not clearing widgets every single time the after_setup_theme action is fired. Instead, we’re only looking to clear the widgets one time.

Also, since this is a destructive action, a case can be made that this should be triggered by the user’s taking some type of action in the dashboard and that it should require confirmation, but that’s outside the scope of what’s being shared.

Regardless, the point is that there’s a difference between unregistering widgets and deactivating widgets, and this is how you can programmatically deactivate WordPress widgets.


  1. Hasin Hayder

    Nice one, Tom. Just curious, how to deactivate a particular widget from the sidebar, or maybe add a few in the current sidebar?

    • Tom

      In order to deactivate a particular widget, you’d need to iterate through the de-serialized array in the database, remove the one you want deactivated, and update the option again.

      As far as programmatically adding one to the current sidebar, this would require that you know which sidebar you want to add it to, to check to see if another instance already exists, and then to add it if it isn’t there (or may you want to add multiple).

      Unfortunately, I don’t have code readily available for that, but maybe the above procedure well help you with that.

  2. Silvan Hagen

    A while ago I created a simple plugin that let’s you deactivate the sidebar Widgets and the Dashboard widgets of your WordPress install, might take a look at the code. I’ll probably update it for multisite one day:

  3. Ata Nemani

    Hi Tom,

    it was great, thank u :)

    • Tom

      Glad to have been of some help!

  4. Adam

    How about removing the “Appearance > Widgets” menu link completely, and blocking any access to that page should someone, somehow, know the URL?

    • Tom

      This is likely your best resource, but if you’re curious about the entire menu’s organization then check out this post. Ultimately, you should be able to remove the ‘Appearance’ menu from the array of menu items.

      • Adam

        Those resources are great. Thank you, Tom!

        FYI, I can’t see that those 2 text links here in the comments are links. However, the email I received when accepting to receive future comments from this blog post had black, underlined links in the comments included in the email.

        Nice site, and keep up the good work!

        • Tom

          Thanks Adam – that’s the nature of styles :). Regardless, I’m glad you were able to access them.

        • Tom

          Thanks Adam – that’s the nature of styles :). Regardless, I’m glad you were able to access them.

      • Adam

        Turns out that that page is a submenu item, and requires slightly different code to remove. Adding the code below to your function removed the menu item, however, typing the URL to that page still takes me to that page. Almost perfect!

        remove_submenu_page( ‘themes.php’, ‘widgets.php’ );

        • Tom

          So I assume you’re good to go with this? :)

  5. Noahj Champion

    Took me quite awhile to find this simple solution.

    Thanks writing this up this up Tom!

    • Tom

      You got it, Noahj — glad it helped!

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑