3.4 Creating custom shortcuts

Available Actions

Action	Default shortcut	What it does
toggleSearchPanel	alt-q	Opens/closes the Search Panel
toggleQuickCopy	---	Enables/disables Quick Copy mode
		When the Search Panel is visible :
closeSearchPanel	Escape	Closes the Search Panel
focusSearchBar	---	Put the cursor in the search bar
		When viewing the item's metadata :
importMetadata	---	Import the item's metadata to the Roam grap
copyCitekey	---	Copy the item's citekey
copyCitation	---	Copy the item's citation (Roam alias)
copyPageRef	---	Copy the item's citekey as page reference
copyTag	---	Copy the item's citekey as tag

How to setup custom shortcuts

Shortcut objects must list the sequence of keys involved, and refer to them by their name in lowercase (if you know JavaScript, that would be the event.key value). The only exception is the four special keys (Alt, Ctrl, Meta, Shift) which must be named altKey, ctrlKey, metaKey, and shiftKey respectively.

For example, the shortcut sequence alt-p would be described by the following object :

{'altKey': true, 'p': true}

Shortcut objects are assigned to a specific action, inside the shortcuts property in zoteroRoam_settings :

// Note: you should add settings *within* the zoteroRoam_settings object
// that contains your dataRequests -- do not declare it again


// Here we're assigning our alt-p shortcut to the toggleSearchPanel action :

zoteroRoam_settings = {
    // Your dataRequests object should be here :
    dataRequests: {
        apikey: 'XXXXXXXXXXXXXXXX',
        dataURI: 'users/1234567/items',
        params: 'limit=100'
    },
    shortcuts: {
        'toggleSearchPanel': {'altKey': true, 'p': true}
    }
}

// Note that multiple shortcuts can be assigned to a given action.
// This is done by providing an Array of shortcut objects.
// For example, we can assign both alt-p and alt-q to toggle the Search Panel :

zoteroRoam_settings = {
    // Your dataRequests object should be here :
    dataRequests: {
        apikey: 'XXXXXXXXXXXXXXXX',
        dataURI: 'users/1234567/items',
        params: 'limit=100'
    },
    shortcuts: {
        'toggleSearchPanel': [{'altKey': true, 'p': true},
                                {'altKey': true, 'q': true}]
    }
}

The tricky part in creating shortcuts is that there is no universal list of key names - they're dependent on your keyboard hardware, your OS (Windows/Mac/Linux...), and also your browser. This can lead to some unexpected behaviors - especially on Mac, and with international keyboards.

To help make testing easier, I created a small tool that lets you press a combination of keys & returns the corresponding shortcut object. It's not perfect, but hopefully it helps you set up shortcuts that work with your computer and software. You can use it here :

Let me know if you're having bugs/issues with this ! Keyboard mappings are pretty complicated