Skip to content
A Cycle.js driver for keyboard events
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Cycle Keys


Cycle DOM now supports selecting on document and body, so this driver is unnecessary.

This driver for Cycle.js helps you to manage key events on the document easily.

Cycle Keys is stream library agnostic -- you can use it with xstream, rxjs, or any other stream library you like. If you have any issues with a particular library, let me know!


You can install Cycle Keys with npm

$ npm install cycle-keys --save


  • Install Cycle Keys with npm (see above)

  • Import the driver

import {makeKeysDriver} from 'cycle-keys';
  • Initialise the driver by calling makeKeysDriver in your drivers object
const drivers = {
  Keys: makeKeysDriver()
  • Add it to your main function's sources
function main({Keys}) { /* Your amazing main function */ }
  • Call (or any of the methods below) without any arguments to get a stream of all keypresses. You can also call press with the name of a key to only get keypresses for that key. Currently, Cycle Keys supports inputting keys as strings only

Note Cycle Keys relies on keycode, see their documentation for more information about string aliases for keys.


Keys.down() - returns a stream of keydown events.

Keys.up() - returns a stream of keyup events. - returns a stream of keypress events.

Keys.isDown(key) - returns a stream of booleans, true if the given key is currently down, false if the given key is currently up. Must be called with a key argument.

All methods take a key argument. Calling a method with a key argument will return a stream of key events filtered to that particular key.

// return a stream of all keypresses
const allKeypresses$ =;

// return a stream of keypresses on the escape key
const esc$ ='esc');

// return a stream of keypresss on the shift key
const shift$ ='shift');

// return a stream of booleans describing whether the enter key is down or up
const isDown$ = Keys.isDown('enter');


In this example, a user can hit 'enter' to change the background colour. The heading text will change depending on whether the space bar is in a down or up position.

You can try this example out online

import {run} from '@cycle/core';
import {makeDOMDriver, p, h1, div} from '@cycle/dom';
import {makeKeysDriver} from 'cycle-keys';
import xs from 'xstream';

function main({DOM, Keys}){
  const colours = ["#F6F792", "#333745", "#77C4D3", "#DAEDE2", "#EA2E49"];

  const isDown$ = Keys.isDown('space');

  const colour$ ='enter')
    .map(ev => +1)
    .fold((acc, int) => acc + int, 0)
    .map(int => colours[int % colours.length]);

  const state$ = xs.combine(isDown$, colour$)
    .map(([isDown, colour]) => ({isDown, colour}));

  return {
    DOM: state$.map(state => (
        {style: {background: state.colour}},
          h1(state.isDown ?
            "Oooh fancy!" :
            "Hold down the space bar. Go on, I dare you."
          p("For additional fun, hit enter")

const drivers = {
  DOM: makeDOMDriver('.app'),
  Keys: makeKeysDriver()

run(app, drivers);
You can’t perform that action at this time.