Running MouseView.js experiment using PsychoJS-PsychoPy

The PsychoPy Builder is a free tool to create experiments that can also write your experiment to JavaScript (PsychoJS) to run online. You can download PsychoPy here: Most PsychoPy experiments are hosted online using

Let's talk through how to get your MouseView.js experiment up and running using PsychoPy.

Fork a demo#

A template of mouseview is already available for you to use and adapt here and the files can be accessed here

To use it, sign into your account (if you don't have one you can sign up for one for free). Go to and select the "fork" icon, when it asks you what "namespace" you want to fork to select your username - now you have your own copy ready to use on pavlovia!

Edit the demo using PsychoPy Builder#

OK so now you have a copy, you probably want to make edits. Be aware that this demo was made in a 2021 release of PsychoPy, so if you are running an older version you might need to update first. Once in builder, select the "search" icon (central globe with a magnifying glass on the toolbar). Look for "mouseview_demo" saved under your username and select "Sync".

Now you have a copy of the mouseview demo to build on yourself! (the changes that you make to this copy will not affect the original repository)

Make your edits!#

This demo is a spin off of the dynamic_selective_inspect demo in pavlovia which does something similar, but less cool. With mouseview you can dynamically manipulate the parameters of your mask in a much more flexible way.

General settings#

Before our search trial, the general settings for each parameter are initialized in the "init_mouseview_trial" routine. The parameters are set in the "init_mouse_view_code" code component as follows:

// Show the cover (hidden by mouseview after it's initialized
$('#cover').css('opacity', 1);
// Settings for mouseview
mouseview.params.overlayColour = '#fff'; //String containing CSS Keyword, hexadecimal, or HSL code.
mouseview.params.overlayAlpha = alphaLevel; //Number-Decimal (0-1). this can be a number but here we are demonstrating how you could feed in parameters from a conditions file
mouseview.params.overlayGaussian = blur; //Number-Integer (pixels)// again we are setting this using a conditions file on each trial
mouseview.params.overlayGaussianInterval = 1000; //Number-Integer or Float (milliseconds)
mouseview.timing.sampleRate = 16.66; //Number-Integer or Float (milliseconds) PLEASE NOTE THIS IS DEPENDANT ON THE REFRESH RATE OF THE MONITOR
mouseview.params.overlayGaussianFunc = ()=> {$('#cover').css('opacity', 0);};// remove the cover when the overlay has been initialized
mouseview.params.apertureSize = '10%'; // Number-Integer (pixels) or String (โ€˜x%โ€™)
mouseview.params.apertureGauss = 10; //Number-Integer (pixels)
// initiate mouseview, go to next routine when done
$.when(mouseview.init()).then(() => {
continueRoutine = false;

For more information on each parameter, see the mouseview article itself. MouseView is preprared in the the "intro_mouseview_trial" routine, where we import the MouseView library and create a "cover" that blocks the scene whilst the overlay is being created, preventing any sneak previews of your stimuli:

// Load the MouseView module.
// MouseView attaches itself to the window as mouseview, so use it
// via the variable "mouseview"
import * as MouseViewModule from './js/MouseView-0.2-alpha.js';
// Create cover screen that we use to hide contents until mouseview is ready
let coverElement = document.createElement("div"); = "background: #808080; position: fixed; bottom: 0; right: 0; left: 0; top: 0; opacity: 0; pointer-events: none;";
coverElement.setAttribute('data-html2canvas-ignore','true') = 'cover'

When the trail starts#

In the mouseview_trial itself there are some snippets of code of iterest in the "mouseview_code" code component

At the begining of the routine we start the tracking:

// Start recording

Note, if you are just interested in mouse coordinates you can set "save mouse state" in mouseview_mouse to everyframe. In the end routine tab:

mouseview.stopTracking();//stop the tracking
mouseview.removeAll();//remove the mouseview overlays
psychoJS.experiment.addData('mouseview',;// save the data to the output file

The routine is currently set to end on a click (because of the settings in the mouseview_mouse).

Changing mouseview parameters trial-by-trial#

In the demo, alpha and blur are manipulated from a conditions file by having a column called "blur" and a column called "alphaLevel", in theory, this should be possible for any parameter of mouseview enabling the manipulation of viewing conditions on a trial-by-trial basis (for example to gradually increase task difficulty!).