jsPsych: behavioral experiments assembled from plugins in a timeline

The unit of the framework is a plugin

jsPsych is a JavaScript framework for creating behavioral experiments that run in a web browser, and the design decision that makes it work is the plugin.

Experiments are created using plugins, and each plugin defines different kinds of events, like showing an image on the screen, and collects different kinds of data, like recording which key was pressed at which time. Assembling different plugins together into a timeline makes it possible to create a wide range of online experiments.

That is the whole model, and it is worth contrasting it with the way people usually write a study. A typical experiment script is a long function with a state machine, a timer, an event listener and a data array, and the data ends up in whatever shape the author felt like that day. In jsPsych, a trial is a list of plugin invocations, each with a type and a set of parameters, and the framework runs them in order, handles the timing, collects the responses and hands back a data object with a consistent shape.

The plugins come in two flavours. Some do general things, like present a stimulus, whether text, image, audio or video, and record a key press or button response along with a response time. Others do specific things, like showing a set of instructions pages, running a drag-and-drop image sorting task, or calibrating the WebGazer eye-tracking extension.

And often people can create their experiment by combining these plugins together. That is the intended path, and the library is designed so that most studies need no custom code at all.

When the combinations are not enough

The escape hatch is the plugin template, and the README is emphatic about how flexible it is.

If the combinations do not work for your experiment, you can modify a plugin file or create your own plugin, and the plugin template is described as extremely flexible. The claim that follows is the one that matters for a research tool: if a task is possible to do in a web browser, you can almost certainly implement it as a plugin.

That claim is what makes jsPsych a framework rather than a set of scripts. A study that needs a stimulus no existing plugin presents, or a response device no existing plugin records, does not have to leave the framework. It becomes a plugin, it is added to the timeline, and it produces data in the same shape as everything else.

The consequence for a reviewer of the study is worth noting. Because the timeline is declarative and the data collection is uniform, the analysis code does not have to special case the parts of the study that were custom. That is a practical benefit to reproducibility, which matters more to this audience than to most.

The extension system fills some of the same ground from the other direction, with the eye-tracking calibration being the example given, and the repository contains a release for an extension called pipe alongside the core package.

The data model, seen through the examples

The examples directory is the best documentation of the data model, because the file names are the API.

There are examples for adding properties to the data, for a data field whose value is a function rather than a constant, for pulling data from the timeline, and for pulling data from a URL. There is an example for aborting the current timeline and one for aborting the whole experiment, an example for adding a trial to the end of a timeline, and one for conditional and loop functions, which is how a repeated or skipped trial is expressed.

The rest of the list shows the shape of a study rather than the API. There is a flanker demonstration, a simple reaction time task demonstration, a browser check example, which is how a study verifies that the participant's browser and input are suitable before the real trials begin, an audio button response plugin, an audio keyboard response, an audio slider response, a CSS classes parameter example, a case sensitive responses example, an animation example, and a plugin for recording video from the browser as an extension.

The through-line is that a study is a sequence of trials, each trial is a sequence of plugins, and the data comes out with one row per trial. The examples are HTML files that you can open directly in a browser after downloading a release, which means the quickest way to understand the framework is to open one and read it.

The repository: a monorepo with a build and a docs pipeline

The layout shows a project that has grown into a proper monorepo, and the tooling is worth understanding if you want to contribute or to build from source.

The root package is private and declares a workspace over packages/*, so the library and its extensions are separate packages in one repository. The build is driven by turbo, which is what makes the per package build and type check scripts composable, and the test runner is Jest configured per package through a projects list pointing at each package's jest.config.cjs.

Releases go through changesets, and the version script does more than bump numbers. It runs the version step, installs, and then calls two Gulp tasks, one to update the unpkg links and one to update the plugin versions, which means the published plugin list and the CDN URLs stay consistent with the new version rather than being edited by hand.

There is also a Gulp task for the core distribution archive, and Husky with lint-staged and Prettier for the commit hooks, with an import sorting plugin configured for TypeScript and JavaScript files.

The documentation is a second toolchain, and it is a Python one. The pyproject file is a Poetry project with package mode disabled, used only for the docs, pulling mkdocs, the material theme and mike, which is the tool that publishes versioned documentation. So the repository runs a Node toolchain for the library and a Python toolchain for the docs, and the docs scripts both install the Python dependencies before serving or deploying.

Loading it, and the tutorials that get you started

jsPsych can be loaded into a project in a variety of ways, including via CDNs and through NPM, and the project documentation takes you through it step by step.

The first tutorial is the hello world tutorial, which is about setting up a project rather than about psychology. The second is the reaction time task tutorial, and the README recommends it as a great next step because it covers many core topics and features. There are also a number of community tutorials available on the website.

That sequencing is a good sign about the project's maturity. The classic reaction time task is the smallest experiment that exercises the whole model, a stimulus, a response, a response time and a trial structure, so a tutorial built around it covers the framework rather than one study.

The examples are distributed with the releases rather than in the repository alone. The instruction is to download the latest release and double-click on an example HTML file to run it in the browser, and to open it with a programming-friendly text editor to see how it works. That is a deliberately low friction path, and it means someone evaluating the framework can see a complete experiment in a browser without installing anything.

The plugin list on the website is the other place to look before building, since most questions about feasibility are answered by what the plugin list already contains.

The people, the funding and the citation

For a library used in academic work, the citation instructions and the funding history are part of the story.

The preferred citation is a 2023 paper in the Journal of Open Source Software, de Leeuw, Gilbert and Luchterhandt, on jsPsych enabling an open-source collaborative ecosystem of behavioral experiments. It is described as an updated description of the library that includes all current core team members, and it replaces an earlier paper by de Leeuw from 2015 in Behavior Research Methods.

The README makes the point about why citing matters in a sentence that is unusual for a library, that citations help demonstrate the library is used and valued, which allows the project to continue working on it. For a project that exists to serve a research community, that is the honest framing.

The project was created by Josh de Leeuw and is currently managed by a core team of four, de Leeuw, Becky Gilbert, Björn Luchterhandt and Jade. The funding history is spelled out, with a Mozilla Open Source Support award that funded development of the library from 2020 to 2022, and a National Science Foundation grant that funded work on the broader ecosystem from 2024 to 2026. The two grants funded different things, which is worth noting, because the ecosystem of plugins and extensions is a different body of work from the core library.

The project is tested with BrowserStack, which matters more than it might appear, because a behavioral experiment that behaves differently in a browser is a data collection problem rather than a cosmetic one, and the OpenSSF Best Practices badge in the header suggests the project is being held to a wider standard than a hobby library would be.

The last push to the repository was on 2026-10-13, with jspsych 8.3.0 released in July 2026 and the config and pipe extension packages released in September.

Editorial conclusion

Adopt jsPsych if you run cognitive or behavioral studies where response timing and trial structure have to be precise, because the plugin model gives you both and the data comes out structured rather than assembled by hand. Do not adopt it for a survey with no timing requirements, where a form builder will do the same job faster. Before you build, read the reaction time task tutorial, and check the plugin list first, because the answer to most design questions is that a plugin already exists.

Frequently asked questions

Official sources

1. jspsych/jsPsych on GitHub
2. License: MIT
3. Project website
4. README
5. Releases