Page Overlay shows analytics data directly on your website.

By doing this, it takes you closer the experience of your visitors and helps you understand traffic patterns.

How to Open Page Overlay for a Page?

Page Overlay can be launched from the rows of the Behaviour > Pages reports. Just move you mouse over the page you want to see the Overlay for and click the bubble icon. It will open Page Overlay in a new tab.

Understanding the User Interface

Page Overlay displays the actual website and puts bubbles next to the links on the page that show how many visitors clicked the link:

Next to your website, there’s a sidebar with additional data and actions:

  • On top, you can pick the date range Page Overlay shall show statistics for. It contains several shortcuts that are much easier to use than a full date selector. The default date range is « Current Month »: when you launch Page Overlay, this date range will always be selected regardless of the date that was selected in Matomo (Piwik) when the Overlay session was launched.
  • Beneath the date picker, you can see the page you are viewing. The location shown here corresponds to the page URLs shown in the page report, so ignored parameters won’t be included here.
  • The section « Main Metrics » shows you the data you would see in the corresponding row of the pages report.
  • On the bottom, you can launch the row actions that you would also see on the pages report: Row Evolution and Transitions.

You can click links inside the website and Page Overlay will update the sidebar and also show analytics data for each page you visit (as long as it has the Matomo tracker on it). And it doesn’t only show data for internal links, it even works for downloads and outlinks.

When you hover a link, the target URL is shown in the lower right. Also, you can see the absolute number of clicks and how many links point the the exact same location.

« 3451 clicks from one of 2 links » means that there are two links on the website that lead to the same URL. The URL was visited 3451 times directly after viewing the current page, so up to 3451 visits must have used one of the two links to get there.

It is important to understand that Page Overlay doesn’t really record the click on the link. Instead, it uses the data Matomo gathers anyway to determine which pages were viewed directly after visiting the current page. If there are multiple links to this page, it cannot tell which link was used how many times. This is why Page Overlay shows you how many links point to this location and it also highlights the bubbles next to the other links when you move your mouse over one of them.


Matomo Page Overlay lets you see how links perform by looking at your actual website. With this visualization, you can derive additional insight like which areas of the website perform better or worse than others.

Together with the Transitions report, it helps you understand the paths visitors take in your website. Clicking through your website and seeing the paths takes you much closer to your visitors and gives you new ideas for improving your content and navigation.

Page Overlay Troubleshooting

1. It doesn’t work at all

  • Make sure the page you want to view in Page Overlay has the Matomo tracker code on it.
  • If you use Browser extensions to block scripts such as Adblock plus or Ghostery, disable them when using Overlay feature. Similarly make sure your browser passes the Referrer field (some extensions or browser settings can disable this).
  • If other JavaScript code in your website contains errors, the Page Overlay Java Script might not work.
  • Maybe your website uses jquery in a very old or hacked version. Page Overlay uses jquery and if it detects that your website is already using it, it will try to use your implementation.
  • If you get an error « Refused to display ‘’ in a frame because it set ‘X-Frame-Options’ to ‘deny’. », then your website sends the HTTP header X-FRAME-OPTIONS to SAMEORIGIN (or DENY) and this prevents Matomo from iframing your website for the Overlay report. To fix this problem, on your website(s) do not send the X-FRAME-OPTIONS HTTP Header.
  • Showing the sidebar requires the page to be opened in a frame. If your website has a frame buster, that will break Page Overlay. But you can still use it without the sidebar by using the config option overlay_disable_framed_mode.
  • Page Overlay depends on the Transitions plugin. That means that Overlay only works if Transitions is enabled too. (Obviously, the Overlay plugin needs to be enabled too.)
  • Page Overlay tries to load scripts and data from the URL you pass to the Matomo tracker. If you have a restrictive mod_proxy setup or there’s another reason why this doesn’t work, use the method setAPIUrl(apiUrl) of the Matomo tracker to let it know from which URL it should load the scripts and the data. The parameter apiUrl has to point to the root directory of piwik, e.g. or The call to setAPIUrl has to be made before calling trackPageView.

Since redirects are not tracked in Matomo, links that point to URLs that will redirect to a different URL can’t be annotated in Page Overlay. The most common case when this happens is when a navigation includes a category that shows a submenu after clicking it and redirects to the first subcategory.

3. I get the error « The Page Overlay session couldn’t be launched yet »

Usually, the website notifies the sidebar of its location. This error means that the notification is not sent.
Possible causes are:

  • If Matomo is currently loaded over SSL, Page Overlay will try to load the website over SLL too. If your website doesn’t support https, that is your problem. You can use Matomo over http and the website will be loaded over http as well.
  • The page you open in Page Overlay needs to have the Matomo tracker in it.
  • If the page you want to view in Page Overlay contains a redirect, the session can’t be launched.

4. I have multiple domains and it doesn’t show all data

Matomo Page Overlay can handle URLs with http or https and with or without www. If you have different domains, it will record the pages as different actions and Page Overlay will only show you the following pages for one domain. To avoid this, you can use the Java Script tracker method setCustomUrl() to track pageviews for only one domain by replacing alias domains with the main domains in Java Script.

5. I have a high traffic website and it takes a long time until the bubbles appear

If you see « loading following pages… » in the lower right for a long time, that means that your Matomo server can’t find the following pages quickly. To find these pages, Overlay uses the Transitions in the background. Therefore, speeding up Transitions is identical to speeding up Page Overlay.

To solve your problem, please take a look at the FAQ about speeding up Transitions.