When a user activates the TwentyEleven theme in the admin widgets area, the user already has the Main Sidebar populated with a few standard widgets. Could someone explain or point me in the right direction about how I could implement the same behavior for my widgets on another theme?


That's not actually installed by the theme. Those widgets are set up as soon as you install WordPress the first time. It's just that if your theme doesn't support widgets, you won't see them.

The part of WordPress that "installs" these widgets can be found in wp-admin/includes/upgrade.php inside the function wp_install_defaults. Here is the relevant part of the code. You should be able to retrofit to your own widgets:

// Set up default widgets for default theme.
update_option( 'widget_search', array ( 2 => array ( 'title' => '' ), '_multiwidget' => 1 ) );
update_option( 'widget_recent-posts', array ( 2 => array ( 'title' => '', 'number' => 5 ), '_multiwidget' => 1 ) );
update_option( 'widget_recent-comments', array ( 2 => array ( 'title' => '', 'number' => 5 ), '_multiwidget' => 1 ) );
update_option( 'widget_archives', array ( 2 => array ( 'title' => '', 'count' => 0, 'dropdown' => 0 ), '_multiwidget' => 1 ) );
update_option( 'widget_categories', array ( 2 => array ( 'title' => '', 'count' => 0, 'hierarchical' => 0, 'dropdown' => 0 ), '_multiwidget' => 1 ) );
update_option( 'widget_meta', array ( 2 => array ( 'title' => '' ), '_multiwidget' => 1 ) );
update_option( 'sidebars_widgets', array ( 'wp_inactive_widgets' => array ( ), 'sidebar-1' => array ( 0 => 'search-2', 1 => 'recent-posts-2', 2 => 'recent-comments-2', 3 => 'archives-2', 4 => 'categories-2', 5 => 'meta-2', ), 'sidebar-2' => array ( ), 'sidebar-3' => array ( ), 'sidebar-4' => array ( ), 'sidebar-5' => array ( ), 'array_version' => 3 ) );

So what you (probably) want to do is run code similar to the stuff listed above upon first activation of your theme. I think this potentially causes some philosophical problems, if you are forcing certain widgets in certain areas. It definitely raises the question: "should these be widgets? Or should they be baked into your siedbars.php file, if they're not really optional?" Widgets are designed to be added or removed by the admin, and should not be required for a theme to operate.

Anyway, that's the official stance, but if you are still set on it, take a look at the 'after_switch_theme' hook as a potential activation hook for your theme. You'll probably only want to run this once, so set an option on the database once you've "activated" your theme and check that option before registering the activation hook.

It should be noted, for anyone else stumbling upon this little snippet, that if you want to override what WordPress installs when it is run for the first time, you can:

  1. Create a file in wp-content/install.php
  2. Within that file, define a function called wp_install_defaults(). This function will supplant the wp_install_defaults() function defined within upgrade.php
  3. It's a good idea to start by copying the entire wp_install_defaults() function from upgrade.php and paste that into your install.php bootstrap, as a way to ensure that the good stuff you want to keep is still there, because if you define a wp_install_defaults() function, it completely replaces everything in the default function.
| improve this answer | |
  • Excellent explanation, thanks Tom! Actually, I'm not trying to force the users to keep my 'default widgets', I just want to give them a good start. I already have defined in different sidebars.php so they appear after the theme activation and can be easily overwritten by the user in admin. But for users that are not very technical and for widgets with lots of options (sliders, image galleries) I would prefer to already have a 'default widget' in place for the users to modify. – George Grigorita Aug 15 '12 at 18:30
  • Thanks for this - there are hardly any "real" answers out there on how to remove widgets from simply displaying, without removing them from Wordpress completely. – Rob Myrick Apr 13 '13 at 19:11
  • @RobMyrick the best thing of course is just to move the widget out of the sidebar and into the "inactive widgets" section. That way you don't lose any of the configuration data - you just "hide" the widget from being seen. – Tom Auger Apr 15 '13 at 13:29

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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