Integrating The New WooCommerce Navigation Bar

In case you haven’t heard, there are some new additions to WooCommerce coming in version 4.0 next month! In this post we are going to take a closer look at the new WooCommerce Navigation bar, and how developers can integrate this experience in their WooCommerce extensions.

Getting to Know the Nav

The new Navigation Bar introduces a unified navigation experience across all core WooCommerce pages. Since WooCommerce interfaces live in multiple menu areas in WordPress Admin ( i.e. the main WooCommerce menu tree, Product management, and the new Analytics top level menu item ), the navigation bar helps one quickly navigate between these areas, and includes the new Activity Panels to allow quick access to key store management flows.

In this post we will be looking specifically at how to include the navigation bar in your own WooCommerce extension screens. In a subsequent posts we will dive into more details on how you can extend the Activity Panels too.

Including the Navigation Bar

All core WooCommerce screens have registered support for the new navigation bar, and in-lieu of a quick code snippet showing how to do this, we will instead look at a popular extension, and write the code needed to include the navigation bar on their management screen.

If you are more keen for just a TL;DR; – you can jump right to our developer documentation on how to do this too.

Mailchimp for WooCommerce

The plugin we will use for this exercise is Mailchimp for WooCommerce – Mailchimp is a popular service, and the plugin has over 900k installs according the the repository. The plugin creates its own top-level menu item in WordPress Admin and corresponding custom PHP page, so it is a prime example for integrating the navigation bar.

Registering Custom PHP Pages

To show the WooCommerce Admin navigation on existing PHP-powered admin pages (most plugin pages), use the wc_admin_connect_page() function.

Connecting pages uses five parameters to wc_admin_connect_page():

  • id – Identifies the page with the controller. Required.
  • screen_id – Corresponds to PageController::get_current_screen_id() to determine the current page. Required.
  • title – Page title. Used to build breadcrumbs. String or array of breadcrumb pieces. Required.
  • parent – Denotes the page as a child of parent. Used for breadcrumbs. Optional.
  • path – Page path (relative). Used for linking breadcrumb pieces when this page is a parent. Optional.

The most challenging part of determining the arguments above is to get the correct screen_id for use when calling wc_admin_connect_page() – fortunately there is a filter in place that one can hook into to quickly grab that:

add_filter('woocommerce_navigation_current_screen_id', 'woocommerce_admin_log_current_screen_id', 1 );

function woocommerce_admin_log_current_screen_id( $screen_id ){
	error_log( $screen_id );
	return $screen_id;

With the above dropped into a plugin file on my development site, I can then see that when I visit the Mailchimp page in WordPress Admin that the following screen id is shown in my error log: toplevel_page_mailchimp-woocommerce

With that id, we can then register support for the new navigation bar:

if ( function_exists( 'wc_admin_connect_page' ) ) {
	    'id'        => $this->plugin_name,
	    'screen_id' => 'toplevel_page_mailchimp-woocommerce',
	    'title'     => __( 'Mailchimp for WooCommerce', 'mailchimp-for-woocommerce' ),

Keeping with the structure of the Mailchimp for WooCommerce extension, I bundled up this bit of code into the following pull request on GitHub. And here is a screen grab with the new code in place:

More Extending Options

As I mentioned above, please stay tuned for more posts specific to the new Activity Panels and how they can be extended. In case you missed it, we also had a post last week about extending reports in the new WooCommerce Analytics reports.

If you have other areas you are interested in learning about extending in WooCommerce 4.0, please share your ideas in the comments please!

By Timmy Crawford

I reside in lovely Bend, Oregon with my wife and two girls, and of course the requisite two mutts. By day I am an Automattician, and by night and on the weekends... I keep it real.