Theming & Customization

This documentation is for advanced users and developers who would like to customize their theme or make small changes to tweak Sensei’s behaviour.

Please note that our support policy does not include assistance with customizations, so we will be unable to assist with modifying or debugging custom code.


  • Theming – A comprehensive guide to theming in Sensei.
  • Enabling Theme Support – Learn how to declare support for Sensei in your theme.
  • Theme Compatibility – A deep dive into how Sensei theme compatibility works.
  • CSS Structure – All about Sensei’s CSS structure and some best practices to follow when updating the styling.


Theme Compatibility

Sensei’s theme compatibility handling ensures that Sensei looks good on your website’s frontend, no matter what theme you decide to use.

How does it work?

When Sensei displays full-page information on the frontend (for example, a course page, a lesson page, the course results page, a quiz page, etc), it needs to use custom PHP templates in order to display that information properly. Previously, Sensei would do this by overriding the theme’s PHP file for these pages and instead use its own.

The problem with this approach is that Sensei had no way of knowing what markup to generate that would work well with the individual theme’s CSS. As a result, for many themes, Sensei pages had serious display issues (the sidebar was in the wrong place, the content container was full-width instead of the width required by the theme, etc).

Since version 1.12, Sensei’s theme compatibility handling seeks to solve the problem in a different way. Instead of rendering the full page with possibly incompatible markup, it attempts to render the Sensei page content within the content area of the theme’s page.php template.

As a result, when Sensei is running its theme compatibility support, it never tries to render the full markup for a frontend page. Instead, it renders all of the special content and UI in the content area, while allowing the theme’s page.php file to render all of the appropriate wrapper markup. This ensures that the theme’s CSS works with the Sensei page.

How to disable theme compatibility?

For most themes, theme compatibility will be enabled by default. It is disabled in the following two cases:

  • The theme or site explicitly declares Sensei support using add_theme_support( 'sensei' );
  • The theme is implicitly supported by Sensei itself (you can see which themes are supported by Sensei by looking in the includes/theme-integrations directory of your Sensei installation).

If you want to disable theme compatibility, but your theme does not explicitly declare support for Sensei, you may use the following code snippet:

add_action( 'after_setup_theme', 'declare_sensei_support' );

function declare_sensei_support() {
    add_theme_support( 'sensei' );

How to add support for my theme?

Although theme compatibility should work in the majority of cases (and we will continue to work on making it better), in some cases it is better to add explicit Sensei support to your theme or site. To do so, please follow the steps in this document.

Troubleshooting issues


The most likely issue you will come across with theme compatibility is double-rendering of some post data. Because Sensei uses the theme’s page.php template, it’s impossible to know exactly what the theme will render on the page. Sensei’s theme compatibility does its best to handle common items that the theme may attempt to display (the post title, comments section, etc) but it’s possible that the theme will still render something that is also rendered by the Sensei template.

If this is the case, the solution is to find where that item is being rendered in the theme’s page.php template or in Sensei and disable one of them. This may be done with a theme option, a Sensei setting, or a filter, depending on what is being double-rendered.

If you cannot find an option, setting, or filter, then you may need to customize a template in order to remove the double-rendering. You could customize the theme’s page.php template, or the Sensei template that is being rendered. To customize the theme template, you should use a child theme to ensure that your customizations are not overwritten by future updates. If you wish to customize a Sensei template, use these instructions.

Archive Page Issues

Because of the way archive pages work in theme compatibility (e.g. course category, lesson tag, course module, etc), there may be cases where some global variables (e.g. $post, $wp_query) do not have the values that might be expected. Most of the time, this should not be a problem, but it may come up in some cases.

Any code that runs while Sensei’s template is being rendered is guaranteed to have the global variables set as expected. This includes any code that runs within a Sensei action or filter, and any code that runs within the WordPress loop. Also, any code run within a widget will have the globals set as expected.

To prevent issues of this nature, ensure that any code expecting a Sensei object in a global variable runs within one of the cases mentioned above. Any such code that runs outside of those cases may find an unexpected object in the global variable, and thus may not function properly.

Other Troubleshooting

If you are experiencing display or functionality issues on a Sensei page, try switching to the Twenty Seventeen theme, which is implicitly supported by Sensei. If the issue does not exist on the supported theme, then you may be experiencing a problem with the theme compatibility support.

In this case you may want to try following the steps in this document to add explicit support for your theme. It is usually not difficult, but does require looking at some of your theme files, and adding some code snippets to your site.

If the problem persists after all troubleshooting steps, please contact our support team, and they will be happy to help!

Enabling Theme Support

For the most part, Sensei will work nicely with any WordPress theme. Just install a theme, activate it, and you’re good to go!

A small percentage of our users, however, may encounter theme compatibility issues. This advanced level support document is for them.

TLDR: Add the following code snippet to your theme’s functions.php file (if you’re using a child theme), or to a plugin such as Code Snippets:

Technical Background

Theme compatibility issues can occur when the default Sensei content wrappers do not match those of the chosen theme. This is because Sensei pages use templates of their own, and it’s impossible for Sensei to know the exact markup a particular theme uses.

A content wrapper is just an HTML element, usually a <div>, that encloses all of the content on a post or page. These wrapper elements are normally added to allow the theme developer finer control over the appearance of the content.

When there is a mismatch between content wrappers, Sensei’s theme compatibility handling will do its best to render the content correctly. In some cases though, you may find it necessary to explicitly add support for your theme. To do so, you’ll need to add some code that tells Sensei which content wrappers it uses, so that courses and lessons get added in the right location. You will also need to add code that tells Sensei that you have added custom support for your theme.

Declaring Sensei Support for Your Theme

To prevent Sensei from using its default theme compatibility functionality, you must declare Sensei support by adding the following to your functions.php file:

Content Wrappers

The default Sensei content wrappers are in the following files:

  • templates/globals/wrapper-start.php
  • templates/globals/wrapper-end.php

These wrappers will work for most well-built themes.

We also provide custom wrappers for the following themes:

  • _s
  • Storefront
  • Twenty Eleven
  • Twenty Twelve
  • Twenty Thirteen
  • Twenty Fourteen
  • Twenty Fifteen
  • Twenty Sixteen
  • Twenty Seventeen

Note: The wrappers for these themes are stored in the /theme-integrations/ folder and will be loaded automatically if you are using one of those themes. If you’d prefer not to load the wrappers for these themes and provide your own instead, you can prevent them from loading by adding the following code to your theme’s functions.php file:

add_filter( 'sensei_load_default_supported_theme_wrappers', '__return_false' );

If your theme uses a different structure, you’ll need to specify your own content wrappers by adding some code to your theme’s functions.php file, or to a plugin such as Code Snippets.

Specifying Your Own Wrappers

First, you’ll need to find the correct HTML structure for the wrappers. To do that, open your theme’s page.php file and look for the theme’s container divs. These are thedivs that appear before and after the content loop, which is responsible for displaying a page’s content.

Wrappers for the TwentyTen Theme

By default, the Sensei wrappers don’t work well with the TwentyTen theme (don’t worry, if you want to use it, this example will show you how!)

For example, if you look at a single quiz page, you can see how the sidebar is being pushed down below the main content:


If you look at the page.php file for the TwentyTen theme, you can see the HTML that is placed around the content loop:


The opening wrappers are the two openingdivs above the main content loop, and the closing wrappers are the corresponding closingdivs below the loop. You also need to include the get_sidebar function, which will output the sidebar on your Sensei pages.

If your theme’s page.php file is much more complex than this, and you can’t easily tell what the opening and closing wrappers are, you may need to get a developer to help you figure it out. We recommend Codeable or one of our WooExperts.

To make this theme work with Sensei, we need to unhook the default wrappers, and then hook in our own functions to specify the wrappers for this theme.

To unhook the default Sensei wrappers, add the following code to the end of the functions.php file in the theme:

Now hook in your own functions, which specify the correct start and end wrappers for the theme. Add this to the end of the functions.php file:

Now if you view the quiz page again, you’ll see that the sidebar is where it’s supposed to be.


Pagination Wrappers

Prior to version 1.1.0, Sensei used the standard WordPress pagination functions to navigate between courses, lessons, and quizzes. However, we’ve improved this by updating the pagination functions to display the next Course, Lesson, and Quiz, taking into account the order settings and the pre-requisite settings. The files that are used to accomplish this are

templates/globals/pagination-lesson.php – loads pagination for lessons
templates/globals/pagination-posts.php – loads default pagination for courses
templates/globals/pagination-quiz.php – loads pagination for quizzes


Sensei Theming

A comprehensive guide to theming in Sensei.

If your Sensei content isn’t displaying how it should, please check out Sensei & Theme Compatibility.

Sensei’s templating system is simple for developers to understand and to customize in their theme. You will find Sensei’s template folder in the plugin’s root directory, under /templates/ – this is the folder that contains all the HTML that Sensei will output on the frontend.

You can override any of the templates found in this folder by copying them to /yourthemefolder/sensei/ and editing the files there. Sensei will automatically load any template files you have in that folder, and use them instead of its default template files.

This is the safest way to make changes to Sensei’s templates, as it means that your changes will not be overwritten when Sensei is updated.

Making Changes

Before you continue to look at the file structure, please take a look at our template hooks. This will allow you to make the most of your customizations without ever touching the template files.

Course Archives

The course archive page is handled by the following files:

  • archive-course.php
  • loop-course.php
  • content-course.php

The archive will output all course with filters at the top which can be used to further filter the courses listed.

The URL for this page will be the same as the page set within Admin > Sensei > Settings > General > Course Archive Page.

Lesson Archives

The lesson archive page is handled by the following files:

  • archive-lesson.php
  • loop-lesson.php
  • content-lesson.php

These files will display a simple archive list of all lessons that have been created.

Single Course

The individual course page is handled by single-course.php

These files will output the individual course and its contents.

Single Lesson

The individual lesson page is handled by the following files:

  • single-lesson.php

These files will output the individual lesson and a link to the lesson quiz.

Single Quiz

The individual quiz page is handled by the single-quiz.php.

The following files are used by the single quiz page to output questions types:

  • /single-quiz/question-type-boolean.php (True/False questions)
  • /single-quiz/question-type-file-upload.php (File Upload questions)
  • /single-quiz/question-type-gap-fill.php (Gap Fill questions)
  • /single-quiz/question-type-multi-line.php (Multi Line questions)
  • /single-quiz/question-type-multiple-choice.php (Multiple Choice questions)
  • /single-quiz/question-type-single-line.php (Single Line questions)

These files will output the lessons quiz questions and handle submission of the users question answers.

Learner Profiles

The learner profile pages are handled by learner-profile.php

These files handle the display of the learner profiles.

Course Results

The course results page is handled by these template files:

  • course-results.php
  • course-results/lessons.php

These files handle the display of the course results.

Course Categories

The course category makes use of the course archive templates. See above.

My Courses

The My Courses page will show a list of the users Active Courses as well as their Completed Courses. The template file that is used is /user/my-courses.php.

Access Errors

If  a user does not have access to a specific area of the Course, Lesson, or Quiz, the output will be handled by no-permissions.php to display the relevant error message.

CSS Structure

Please note that this is a Developer level document. If you are unfamiliar with code/templates and resolving potential conflicts, select a WooExpert or Developer for assistance. We are unable to provide support for customizations under our Support Policy.


Inside the assets/css/ directory you will find the stylesheets responsible for the default Sensei frontend styles. The files to look for are frontend.scss and frontend.css.

frontend.css is the minified stylesheet. This file is referenced by the plugin and declares all Sensei styles. frontend.scss is not used by the plugin. It contains the raw CSS and can be compiled using Sass, a CSS preprocessor. We use this file to author the plugin CSS.

The CSS is written to make the default styles compatible with as many themes as possible. It is however more than likely that you will want to make your own adjustments.


To avoid upgrade issues it is advised that you do not edit these files directly. Rather you should use them as a point of reference.

If you just want to make a few changes we’d recommend simply adding some overriding styles to your theme’s stylesheet. For example add the following to your theme stylesheet to make Sensei progress bars black instead of the default colour:

.meter > span {background: #000;}

Sensei also outputs “sensei” as a class on the body tag of Sensei pages, which can be useful for overriding styles on Sensei pages only.

Disabling Sensei Styles

If you plan to make major changes then you might prefer your theme not to reference the Sensei frontend stylesheet at all. You can tell Sensei not to use frontend.css in Sensei > Settings. But a better solution is to simply add the following line of code to your theme’s functions.php file:

add_filter( 'sensei_disable_styles', '__return_true' );

With this definition in place your theme will no longer use the Sensei frontend stylesheet, giving you a blank canvas upon which you can build your own desired layout / style.

Remove double ‘Quiz’ word

With some of the older quizzes we stored the word ‘Quiz’ inside the title. This was changed to where the title is only appended when the quiz loads.

This allows you now to translate the word ‘Quiz’. Due to the code update some older Quizzes now loads with 2 ‘Quiz’ words. To fix this add the following to your theme’s functions.php:

Please note that this is a Developer level document. If you are unfamiliar with code/templates and resolving potential conflicts, select a WooExpert or Developer for assistance. We are unable to provide support for customizations under our Support Policy.

Hooks: Actions and Filters

Please note that this is a Developer level document. If you are unfamiliar with code/templates and resolving potential conflicts, select a WooExpert or Developer for assistance. We are unable to provide support for customizations under our Support Policy.

Sensei comes with several hooks that can be used to change the way it behaves. These hooks can in turn be separated into two categories:

  • Actions
  • Filters

If you are not familiar with how actions and filters work in WordPress, this guide can bring you up to speed.

A current list of all action and filter hooks can be found in our Sensei Developer Reference docs.

Code Examples

Here are some code examples using some of the Sensei filter hooks. The code in these examples can be added to your theme’s functions.php file, or loaded via a third-party plugin like Functionality.

Disable the default Sensei styles