In this tutorial we will learn how to create a single theme activation popup message and also a multiple popup theme tour.

Theme Welcome Message

Activation messages and theme tours can be very helpful for new users of your theme. You can point to where an option panel or help menu may be located and introduce them to various custom post types that your theme may include.

What we are developing

The WordPress admin UI has a pointers built in that we can tie into. Perhaps you have seen them before when you activated WordPress SEO or another plugin. Many times, they are used to take you on a tour of the options.

For the first bit of this tutorial we are going to display a single popup message when the user activates the theme. If they close the pointer it will be removed forever.

Developing a Single Pointer

For this tutorial we will be using Underscores, a popular starter theme for WordPress by the folks at Automattic – the company behind WordPress.  If you’re working with your own theme, that’s no problem at all.

Create a new file in includes called theme-welcome.php

Since this is theme specific functionality, we are not going to include this code in a separate plugin. We’re simply going to add our code to a new file in the /inc/ directory and then include it within the functions.php file within the base theme directory to keep things organized.

Add the following code your newly created file:

The code above contains some nice comments to tell you what exactly is going on and when and where.

Include the code in functions.php

Open up your theme’s functions.php file now and include the new file we creating that contains our code. If you’d like you could just add the code above to functions.php file but I’ve included it separate for better organization.

Now Active the Theme

You should now see when you activate the theme a pointer will point at the appearances menu with our message. You can easily customize this message by modifying lines 38-39 in the code.

Moving the Pointer

Depending on your needs, you may want to move the pointer to a different area. The location displayed by the pointer is easy to modify by changing the jQuery selector using on line 45 in code above.

For instance, if I wanted to change the menu location from the settings menu to appearances I would update the selector from #menu-settings to #menu-appearance and this will effectively change the location it displays.

Tip: If you click the close button and want the tooltip to appear again you will need to change the name of the pointer from thsp_settings_pointer to something else because the tooltip value been saved to your user meta. You could remove that option in your usermeta table via MySQL but that’s a bit more work.

Credit for the code above goes to Slobodan Manic over at WP Explorer. For more information on the snippet above and additional helpful scripts like including help menus check out this article.

Create a Theme Tour using Multiple Pointers

Let’s say you have multiple areas you want to highlight in your theme. Let’s create a tour of those areas that the user can click through to become more familiar with your theme.

The idea is simple: when the user activates your WordPress theme they will be greeted with an activation pointer with two buttons, “next” and “close”. The next button will go to another page on WordPress, open another pointer, and allow the user to continue taking the tour.

The following class file should be included within a new PHP document within the /inc/ folder in Underscores. This code will effectively add the tour and store a value in the user’s meta that they have taken the tour. One item worth noting is that you can easily modify the code that includes the class to display only on theme activation or for all users. This can be helpful for creating introduction tours for all users if you run a blog with many authors.

Here is the class to create a theme activation welcome tour:

This is the Gist you can use and Fork to your liking. The following is code is pulling from the Gist:

Again, the code above has comments to tell you what’s going on. Now it’s time to get this class working for our theme.

Include our Class Only on Theme Activation

To include the file only when the theme is activated or when the user is taking the tour add this code to your theme’s functions.php file:

Now try activating your theme. Once activated, you should be taken on a tour that goes through the various sections of WordPress. If the user chooses to close the tour they will no longer see any pointers.


Note: I have tested the code above with the new theme selection area in WP 3.8

It’s About Helping Users

As a user, I like to be welcomed to a new product. If I activate a theme that I don’t have knowledge of it can be confusing off the bat. Providing users a quick message with links to documentation, videos and any additional help can really go a long way.

Please feel free to critique my code and fork to your heart’s delight.

Devin Walker is a San Diego-based WordPress Developer and enthusiast. He is the author of several popular and highly-rated WordPress themes and plugins. In his free time he enjoys playing Golf and traveling.

Follow Devin:

4 Responses to “How to Create a WordPress Theme Activation Message and Tour”

  1. steveorevo

    Perfect. I’m going follow/use this right now!

  2. Spencer Labadie

    Awesome, worked great! Just had to modify a few things to get it to work for plugin use instead of a theme.

  3. foxpc

    Hi Devin,
    Great job!
    i have 2 question.
    how to add “back button” to get back one step before?
    and another question, can i create spirit pointer tour for post then for pages and etc…
    but i want t have some “reset button” that will rest only tour for “post” or “pages” etc… this is good if the client wants to make the tour one more time.


Leave a Reply