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.


Join the conversation! 14 Comments

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

    • 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. 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: https://github.com/wearerequired/WP-Widget-Disable

  3. Hi Tom,

    it was great, thank u :)

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

  5. Took me quite awhile to find this simple solution.

    Thanks writing this up this up Tom!

Leave a Reply