Skip to content

jsPsych "Hello world" experiment

In the long tradition of "Hello world!" examples, this tutorial creates an experiment that outputs the phrase "Hello world!" to the browser. Though useless as an actual experiment, the process is helpful for learning the basics of using the jsPsych library.

Choose your own (setup) adventure

Starting with the release of version 7.0 of jsPsych there are three different ways that you can add jsPsych to your project. Which approach you choose will depend on what your goals are.

  • I want the simplest possible setup. This approach involves using scripts that are hosted on a CDN. You do not need to download or install anything to start using jsPsych. The limitation is that you cannot customize the library. For most experiments, this approach will be sufficient.

  • I want to be able to do some customization, but have a simple setup.. This approach involves downloading a bundle of scripts that make up jsPsych. If you used jsPsych prior to version 7.0, this will feel like the most familiar approach. Having your own copy of the scripts means that you can make modifications to the library such as tweaking plugin behavior.

  • I want to use modern JavaScript tooling, like npm and import statements. You can install jsPsych, plugins for jsPsych, and extensions for jsPsych from NPM. This approach allows you to integrate jsPsych into your favorite JavaScript frameworks and get the benefits of TypeScript, bundlers, and more.

Option 1: Using CDN-hosted scripts

Step 1: Create an HTML file

Tip

To edit jsPsych code you'll need a programming-friendly text editor. A great free option is Visual Studio Code (Windows, OSX, Linux).

Create a new file called experiment.html.

There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
  </head>
  <body></body>
</html>

Add the above code to the experiment.html file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'.

Step 2: Load the jsPsych library

To use jsPsych, add a <script> tag to load the library. We'll load the library from a CDN, which means that the library is hosted on another server and can be loaded without having your own copy.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="https://unpkg.com/jspsych@7.2.3"></script>
  </head>
  <body></body>
</html>

Note that the URL for the jsPsych library includes the version number, which ensures that the behavior of your experiment won't change with any future updates to jsPsych.

You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a <link> tag to the <head> section of the document.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="https://unpkg.com/jspsych@7.2.3"></script>
    <link href="https://unpkg.com/jspsych@7.2.3/css/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
</html>

Step 3: Create a script element and initialize jsPsych

To add JavaScript code directly to the webpage we need to add a pair of <script> tags after the <body> tags.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="https://unpkg.com/jspsych@7.2.3"></script>
    <link href="https://unpkg.com/jspsych@7.2.3/css/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
  <script>
  </script>
</html>

To initialize jsPsych we use the initJsPsych() function and assign the output to a new variable.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="https://unpkg.com/jspsych@7.2.3"></script>
    <link href="https://unpkg.com/jspsych@7.2.3/css/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
  <script>
    const jsPsych = initJsPsych();
  </script>
</html>

Step 4: Use a plugin to print a message

For this demo we want to show some text on the screen. This is exactly what the html-keyboard-response plugin is designed to do. To use the plugin, we need to load it with a <script> tag.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="https://unpkg.com/jspsych@7.2.3"></script>
    <script src="https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.1"></script>
    <link href="https://unpkg.com/jspsych@7.2.3/css/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
  <script>
    const jsPsych = initJsPsych();
  </script>
</html>

Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to jsPsychHtmlKeyboardResponse. We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="https://unpkg.com/jspsych@7.2.3"></script>
    <script src="https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.1"></script>
    <link href="https://unpkg.com/jspsych@7.2.3/css/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
  <script>
    const jsPsych = initJsPsych();

    const hello_trial = {
      type: jsPsychHtmlKeyboardResponse,
      stimulus: 'Hello world!'
    }
  </script>
</html>

Step 5: Run the experiment

Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline. For a simple experiment like this one, the timeline is just an array containing the list of trials to run.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="https://unpkg.com/jspsych@7.2.3"></script>
    <script src="https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.1"></script>
    <link href="https://unpkg.com/jspsych@7.2.3/css/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
  <script>
    const jsPsych = initJsPsych();

    const hello_trial = {
      type: jsPsychHtmlKeyboardResponse,
      stimulus: 'Hello world!'
    }

    jsPsych.run([hello_trial]);
  </script>
</html>

Once you've saved the file, open it in a browser. You should see "Hello world!" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial).

Option 2: Download and host jsPsych

Step 1: Download jsPsych

Start by downloading the latest release of jsPsych. Here's a direct link (jspsych.zip). The most recent version can always be found at the top of the GitHub releases page. Note that even the releases that are for a particular plugin or extension will contain the full set of files needed to run jsPsych locally in the dist archive (zip) release asset. You should download the zip file for whatever the most recently released package is. This will ensure that you have the most recent version of all the packages associated with jsPsych.

Step 2: Create a folder to store your experiment files

Create a folder on your computer to put the experiment files in. We'll call this "MyExperiment" for the tutorial. Add a subfolder called jspsych. Once you've created the folder, open the downloaded archive from step 1 and copy the contents of the dist folder into the jspsych folder. It should look like this:

📂 MyExperiment
--  📂 jspsych
----  📄 jspsych.js
----  📄 plugin-animation.js
----  📄 plugin-audio-keyboard-response.js
----  ...

Step 3: Create an HTML file

Tip

To edit jsPsych code you'll need a programming-friendly text editor. A great free option is Visual Studio Code (Windows, OSX, Linux).

Create a new file called experiment.html in the MyExperiment folder. The directory structure should look like this:

📂 MyExperiment
--  📄 experiment.html
--  📂 jspsych

There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
  </head>
  <body></body>
</html>

Add the above code to the experiment.html file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'.

Step 4: Load the jsPsych library

To use jsPsych, add a <script> tag to load the library. Set the src attribute to the path to the jspsych.js file.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="jspsych/jspsych.js"></script>
  </head>
  <body></body>
</html>

You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a <link> tag to the <head> section of the document.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="jspsych/jspsych.js"></script>
    <link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
</html>

Step 5: Create a script element and initialize jsPsych

To add JavaScript code directly to the webpage we need to add a pair of <script> tags after the <body> tags.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="jspsych/jspsych.js"></script>
    <link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
  <script>
  </script>
</html>

To initialize jsPsych we use the initJsPsych() function and assign the output to a new variable.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="jspsych/jspsych.js"></script>
    <link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
  <script>
    const jsPsych = initJsPsych();
  </script>
</html>

Step 6: Use a plugin to print a message

For this demo we want to show some text on the screen. This is exactly what the html-keyboard-response plugin is designed to do. To use the plugin, we need to load it with a <script> tag.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="jspsych/jspsych.js"></script>
    <script src="jspsych/plugin-html-keyboard-response.js"></script>
    <link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
  <script>
    const jsPsych = initJsPsych();
  </script>
</html>

Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to jsPsychHtmlKeyboardResponse. We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="jspsych/jspsych.js"></script>
    <script src="jspsych/plugin-html-keyboard-response.js"></script>
    <link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
  <script>
    const jsPsych = initJsPsych();

    const hello_trial = {
      type: jsPsychHtmlKeyboardResponse,
      stimulus: 'Hello world!'
    }
  </script>
</html>

Step 7: Run the experiment

Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline. For a simple experiment like this one, the timeline is just an array containing the list of trials to run.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="jspsych/jspsych.js"></script>
    <script src="jspsych/plugin-html-keyboard-response.js"></script>
    <link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
  </head>
  <body></body>
  <script>
    const jsPsych = initJsPsych();

    const hello_trial = {
      type: jsPsychHtmlKeyboardResponse,
      stimulus: 'Hello world!'
    }

    jsPsych.run([hello_trial]);
  </script>
</html>

Once you've saved the file, open it in a browser. You should see "Hello world!" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial).

Option 3: Using NPM

If you are electing to use npm to install jsPsych we will assume that you already are familiar with Node.js and generally know what you are doing with web development. We will also assume that you are using a webpack or a similar bundler.

Info

You may want to check out the jsPsych Builder CLI utility. jsPsych Builder allows you to automate the experiment setup, spin up a development server, and transpile and bundle scripts and styles using webpack. Using jsPsych Builder will automate some of the steps in this tutorial, so if you prefer that option, you may want to switch to the getting started instructions on the jsPsych Builder GitHub page.

Step 1: Install jspsych

Run npm install jspsych.

This installs the core jsPsych package. Plugins and extensions are installed separately.

Step 2: Import the initJsPsych function and create a new JsPsych instance

We create a new instance of the JsPsych class by calling initJsPsych. The instance can optionally be configured via a variety of options, passed as an object to initJsPsych.

import {initJsPsych} from 'jspsych';

const jsPsych = initJsPsych();

Step 3: Static markup and CSS

jsPsych requires nothing but a body element in your HTML document. For the jsPsych stylesheet, depending on your bundler setup, you can either directly import 'jspsych/css/jspsych.css' into your JavaScript file or add a link tag (like <link href="path/to/jspsych.css" rel="stylesheet" type="text/css" />) to your HTML document's head.

Step 4: Install and import a plugin

Install the html-keyboard-response plugin with:

npm install @jspsych/plugin-html-keyboard-response

Then import the htmlKeyboardResponse plugin class.

import {initJsPsych} from 'jspsych';
import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response';

const jsPsych = initJsPsych();

Step 5: Create a trial

Once the plugin is imported we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to htmlKeyboardResponse. We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page.

import {initJsPsych} from 'jspsych';
import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response';

const jsPsych = initJsPsych();

const trial = {
  type: htmlKeyboardResponse,
  stimulus: 'Hello world!',
}

Step 6: Run

Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline. For a simple experiment like this one, the timeline is just an array containing the list of trials to run.

import {initJsPsych} from 'jspsych';
import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response';

const jsPsych = initJsPsych();

const trial = {
  type: htmlKeyboardResponse,
  stimulus: 'Hello world!',
}

jsPsych.run([trial]);