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.

14 Replies to “Programmatically Deactivate WordPress Widgets”

    1. 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.

      1. 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!

      2. 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’ );

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.