jsPsych: Build Browser Behavioral Experiments

jsPsych is a free, open-source JavaScript framework for building behavioral experiments that run in a web browser. This guide is for researchers who need to put a reaction-time or key-press task online and want to know what jsPsych is, how to install it, how to run a first trial, how to export the data, and where to host the finished study. Details were read from the official jsPsych documentation on 2026-11-08.

What jsPsych is used for in research

According to the official documentation, jsPsych is “a JavaScript framework for creating behavioral experiments that run in a web browser.” Experiments are built from plugins: each plugin defines an event, such as showing an image or collecting a key press, and records the resulting data. Plugins are assembled into a timeline that the framework runs in order. Typical uses are stimulus-presentation and response-timing tasks in psychology and cognitive science, run either on a lab computer or online with remote participants.

The library is released under the MIT license (copyright Joshua R. de Leeuw), so it can be used, copied and modified for research without a licence fee, and the code can be archived alongside a study for reproducibility. See the jsPsych license page.

Install or access (official sources only)

The official Hello World tutorial describes three ways to get jsPsych. Choose one; they all provide the same library.

Method	What you do (per the tutorial)
CDN (fastest start)	Load the library from unpkg.com in your HTML file, for example https://unpkg.com/[email protected], with the matching stylesheet https://unpkg.com/[email protected]/css/jspsych.css. The participant’s browser needs internet access to reach the CDN.
Download	Download jspsych.zip from the latest release on the jsPsych GitHub releases page and copy the contents of the dist folder into a jspsych folder in your project.
npm (bundler)	Run npm install jspsych, then install each plugin you need, for example npm install @jspsych/plugin-html-keyboard-response. The tutorial recommends this route when you use a bundler.

Version numbers in the tutorial (jsPsych 8.3.0 and the html-keyboard-response plugin 2.2.0 when read) change as new releases appear. The tutorial notes that the CDN address includes the version number, which keeps an experiment’s behavior fixed instead of changing with later updates. Record the exact versions you used for the methods section of your paper.

Step-by-step: run your first trial

This is the CDN version of the official Hello World example. Save it as experiment.html and open the file in a web browser.

1. Create experiment.html with an HTML skeleton and a title.
2. In the head, load the jsPsych library script, the plugin script and the stylesheet link.
3. In a script block, initialize jsPsych with const jsPsych = initJsPsych();.
4. Define a trial object whose type is the plugin and whose stimulus is the content to show.
5. Start the timeline with jsPsych.run([hello_trial]);.

<!DOCTYPE html>
<html>
  <head>
    <title>My experiment</title>
    <script src="https://unpkg.com/[email protected]"></script>
    <script src="https://unpkg.com/@jspsych/[email protected]"></script>
    <link href="https://unpkg.com/[email protected]/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>

Expected result: “Hello world!” appears, and pressing any key ends the trial and removes the text. With the npm route, the same trial imports the library with import {initJsPsych} from 'jspsych'; and uses the plugin name htmlKeyboardResponse instead of the global jsPsychHtmlKeyboardResponse.

Real experiments add more trial objects to the array passed to jsPsych.run(), each using the plugin that fits the task. Source: jsPsych Hello World tutorial.

Output and how to read it

Plugins save their own data as each trial runs, and you reach it through jsPsych.data.get(). The data overview documents these calls:

• jsPsych.data.get().csv() and jsPsych.data.get().json() export the full data set as CSV or JSON text.
• jsPsych.data.get().filter({trial_type: 'image-keyboard-response'}) keeps trials from one plugin; filterCustom() accepts a function, for example one that keeps trials with rt between 100 and 500.
• first(n), last(n), count() and select('rt') return subsets and counts; the documentation shows descriptive statistics such as mean(), sd() and median() applied to a selected column.

Fields named in the documentation include rt (response time), response (the key pressed), trial_type (the plugin that produced the trial) and correct. Variables such as subject or condition can be attached to every row with jsPsych.data.addProperties().

To keep data from an online run, send it to a server when the experiment ends: the documentation’s example calls saveData(jsPsych.data.get().csv()) from on_finish, with a PHP script writing a CSV file, or posts the JSON to a script that writes to MySQL. It notes that files saved in a web directory carry security risks unless access is blocked or the folder sits outside the web root, and presents the database approach as more secure. The call-function plugin’s async option can hold the experiment until the upload finishes so data is not lost if a participant closes the window early. Source: jsPsych data documentation.

For data management, treat the exported CSV as the raw record, keep the experiment code and pinned versions with it, and document the columns in a data dictionary. If you host on a study server, the CASRAI guide to JATOS describes one option.

Troubleshooting

• The trial type is not defined. The tutorial loads the plugin as its own script (or npm package) in addition to the library; the trial’s type refers to that plugin, so confirm the plugin is loaded.
• Behavior changed after an update. Pin the version in the CDN address, as the tutorial describes.
• Nothing is saved when run offline. The Running Experiments page states that running an HTML file in a browser involves no database; data is displayed, logged to the console or saved locally, so add an export step before collecting real data.
• Data lost when a participant closes the window. Use the async option of call-function so the upload finishes first.

Where to run the study: hosting and recruitment options

The official Running Experiments page lists options for putting a jsPsych study online. The table restates that page; it does not include pricing, which you should read from each provider.

Option	What the jsPsych docs say
Cognition.run	Free hosting service built for jsPsych.
JATOS	Free, installed on your own server, with a graphical interface for studies and data and support for multiple researchers. See the CASRAI guide to JATOS.
Pavlovia	Paid service from the PsychoPy team, based on GitLab repositories.
psiTurk	Python-based, built around Amazon Mechanical Turk.
Pushkin	Full lab website with participant logins.
Do it yourself	Your own server stack, such as LAMP/LEMP, Flask or Node.js.

For recruiting participants, the page names SONA, Prolific and Mechanical Turk; MTurk has jsPsych helper functions. For the platform side, see the CASRAI guide to Amazon Mechanical Turk and the comparison Prolific vs MTurk. Source: jsPsych Running Experiments.

Free alternatives and related tools

The jsPsych documentation itself points to JATOS, Cognition.run and Pavlovia as places to host jsPsych studies rather than as replacements. For a commercial, desktop-oriented tool for the same kind of task, see the CASRAI guide to Inquisit.

Frequently asked questions

What is jsPsych?

A JavaScript framework for creating behavioral experiments that run in a web browser, using plugins assembled into a timeline (jsPsych documentation, read 2026-11-08).

Is jsPsych free to use?

The library is licensed under the MIT license. Hosting, recruitment and some deployment services are separate and have their own terms.

Does jsPsych need a server?

Not to run an experiment: you can open the HTML file in a browser. Saving participants’ data online requires a server-side or hosted-service setup, as described above.

How do I export jsPsych data?

Call jsPsych.data.get().csv() or .json() and save the result, locally or by sending it to a server.

Sources (official documentation, read 2026-11-08)

• jsPsych documentation home
• Hello World tutorial
• Data overview
• Running experiments
• License