Configure keyboard shortcuts

Add keyboard shortcuts for the frequently used interface elements. This will help users because keyboard combinations are somewhat faster than mouse clicks.

In Toloka, shortcuts are particularly helpful because performers will do your tasks faster and you can pay less for the tasks. If your project has a low score for “Interface usability”, adding shortcuts will help improve the rating.

Shortcut features

Shortcuts are digits or letters shown next to buttons. Shortcuts help users do an action by pressing a key.

A shortcut is always added to a button if they do the same thing.

Keyboard shortcuts are independent of the interface. They work even if they are not displayed, like if you set up a shortcut without setting up a button.

Some components provide additional ways for setting up shortcuts. For example, the field.image-annotation component has its own plugin.

How to configure shortcuts

Use a separate plugin to configure shortcuts: plugin.hotkeys. Use this plugin to assign keys to actions. Plugins are added to the plugins array in the configuration root.

  {
    "type": "plugin.hotkeys",
    "p": {
      "type": "action.play-pause",
      "view": {
        "$ref": "view.items.0"
      }
    }
  }

In this example, pressing P triggers the action.play-pause action. It starts or pauses playback in the player. The player is specified in the view property by using the $ref structure, which links to another place in the configuration.

View example in the sandbox.

Tip. Mind the keyboard layout when setting up shortcuts: if you choose a character that looks similar in the Cyrillic and Latin layouts, this might confuse Russian users.

Radio buttons and checkboxes

Use the action.set component to set up shortcuts for radio buttons. For checkboxes, use action.toggle. Assign shortcuts to actions that your radio buttons or checkboxes do.

View example in the sandbox.

Reusing shortcuts

You can reuse shortcuts just like any other code fragments. To do this, use the structure { "$ref": "path.to.element" }. Reuse is helpful when you need to insert the same shortcuts in multiple places in your code.

View example in the sandbox.

Tip. Put your reused code into vars so that you don't have to change the path in the $ref property when you change the configuration.

Multiple actions

For the user to trigger multiple actions by pressing a button, add the action.bulk component. For example, you can use it to show multiple notifications.

View example in the sandbox.

Conditions in shortcuts

If you use a condition (helper.if or helper.switch), also add it to the shortcut to ensure consistency.

If you set up a shortcut without a condition, the shortcut will still work, but won't be visualized. This might cause errors.

Here is an example of an error. In this example, if the user responds Yes, they see another question. But they can use a keyboard shortcut to respond to it, even if it's not shown in the interface.

View example with error in the sandbox.

View corrected example in the sandbox.

Troubleshooting

To display a shortcut in the interface, set the shortcut to the same action that is performed when the button is clicked.

Assign an action to the component if you haven't yet:

You can see the full list of actions in List of actions.

Keep in mind the following:

  • The data types for actions must be the same. For example, in the following case the shortcut works but is not displayed: clicking on the button saves the “true” string to the results, and the Boolean value true is defined for the shortcut.
  • If multiple actions are triggered when the button is clicked (action.bulk), the sequence of these actions for the shortcut must be the same.
  • If you use a conditional operator to select an action, such as helper.if, the same conditional operator (helper.if) must be called under the same rules when the shortcut key is pressed.