Keyboard shortcuts and commands


  1. Key mapping
    1. Map commands
    2. Map options
    3. Mapping timeout
    4. Key sequences
    5. Special characters
  2. Abbreviations
  3. User-defined commands
    1. Grouping
    2. Argument handling
    3. Argument completion
    4. Custom completion
    5. Count handling
    6. Special cases
    7. Command description
    8. Replacement text
  4. Examples

Pentadactyl provides a number of commands to change the behavior of key presses. This can mean anything from automatically substituting one key for another or automatically replacing one typed word for another, to launching a dialog or running a command.

Key mapping

Key mappings are the most basic means Pentadactyl provides for altering the actions of key presses. Each key mapping is associated with a mode, such as Insert, Normal, or Command Line, and only has effect when that mode is active. Although each mode has a full suite of internal mappings, they may be easily augmented, altered, or removed with the :map command and its variants. These commands, in essence, allow the user to quickly substitute one sequence of key presses for another. For instance,

:map <F2> :echo Date()<CR>

causes “:echo Date()<CR>” to be typed out whenever <F2> is pressed, thus echoing the full date to the command line.

Standard key mapping commands are provided for the five most common modes,

Normal mode: When browsing normally
Visual mode: When selecting text with the cursor keys
Insert mode: When interacting with text fields on a website
Text Edit mode: When editing text fields in Vim-like Normal mode
Command Line mode: When typing into the Pentadactyl command line

The ordinary :map and :noremap commands add mappings for Normal and Visual mode. In order to map key bindings in a different mode, any of the mapping commands may be prefixed with one of the above letters. For instance, :imap creates a new key mapping in Insert mode, while :cunmap removes a key mapping from Command Line mode. Other modes can be specified using the -modes option described below.

Warning: It is important to note that mappings are not automatically saved between sessions. In order to preserve them, they must either be added to your pentadactylrc or saved via the :mkpentadactylrc command.

The following tree represents all of the modes understood by dactyl. Mappings for a mode also apply to its children and descendants. So a mapping in the Base mode, for instance, is also active in Normal and Ex mode.

Map commands

:map {lhs} {rhs}
:nm[ap] {lhs} {rhs}
:vm[ap] {lhs} {rhs}
:im[ap] {lhs} {rhs}
:tm[ap] {lhs} {rhs}
:cm[ap] {lhs} {rhs}

Map the key-sequence {lhs} to {rhs} for the applicable mode(s). The keys of {rhs} respect user-defined mappings, so the following will result in an infinite loop,

:map a b
:map b a

In order to avoid this shortcoming, the :noremap command or the -builtin option may be used.

Below is an overview of which modes each map command applies to:

:map :noremap :unmap
Normal and Visual modes
:nmap :nnoremap :nunmap
Normal mode
:vmap :vnoremap :vunmap
Visual mode
:imap :inoremap :iunmap
Insert mode
:tmap :tnoremap :tunmap
Text Edit mode
:cmap :cnoremap :cunmap
Command Line mode

Note: The -modes option, described below, provides a more flexible way to specify the applicable modes.

Map options

Any of the map commands may be given the following options:

Accept an argument after the requisite key press. Sets the arg parameter to the result. (short name -a)
Execute this mapping as if there were no user-defined mappings (short name -b)
Accept a count before the requisite key press. Sets the count parameter to the result. (short name -c)
A description of this mapping (short name -d)
Execute {rhs} as an Ex command rather than keys (short name -e)
Add this command to the given group (short name -g). When listing commands this limits the output to the specified group.
Execute {rhs} as JavaScript rather than keys (short names -js, -j)
Parse the {n}th argument without specially processing any quote or meta characters. (short name -l)
Create this mapping in the given modes (short names -mode, -m)
Do not save this mapping to an auto-generated rc file (short name -n)
Do not echo any generated keys to the command line (short name -s, also <silent> for Vim compatibility)
:no[remap] {lhs} {rhs}
:nno[remap] {lhs} {rhs}
:vno[remap] {lhs} {rhs}
:ino[remap] {lhs} {rhs}
:tno[remap] {lhs} {rhs}
:cno[remap] {lhs} {rhs}

Map the key-sequence {lhs} to {rhs} for the applicable mode(s). The keys in {rhs} do not respect user-defined key mappings, so the following effectively reverses the default meanings of the keys d and D

:noremap d D
:noremap D d
:unmap {lhs}
:nun[map] {lhs}
:vun[map] {lhs}
:iu[nmap] {lhs}
:tu[nmap] {lhs}
:cu[nmap] {lhs}

Remove the mapping of {lhs} (or all mappings if [!] is given) for the applicable mode(s).


List all mappings for the applicable mode(s). Mappings are partitioned into groups.

:map {lhs}
:nm[ap] {lhs}
:vm[ap] {lhs}
:im[ap] {lhs}
:tm[ap] {lhs}
:cm[ap] {lhs}

List all mappings starting with {lhs} for the applicable mode(s).

Mapping timeout

When Pentadactyl receives a key event that has a separate binding and at the same time is part of a key chain, values of the 'timeout' and 'timeoutlen' options are used to decide what to do. See the documentation of those options for more information.

Key sequences

Most keys in key sequences are represented simply by the character that you see on the screen when you type them. However, as a number of these characters have special meanings, and a number of keys have no visual representation, a special notation is required.

In order to represent key presses using the Control, Alt, Meta, or Shift keys, the following prefixes may be used,

  1. <C-␣>: The control or ctrl key.
  2. <A-␣>: The alt key.
  3. <M-␣>: The meta key, windows key, or command key.
  4. <⌘-␣>: Same as <M-␣>.
  5. <S-␣>: The shift key.

These prefixes can be combined however you see fit.

Note: Within angle brackets all alphabetic characters are read as lowercase. Uppercase characters can only be specified with the S- modifier.

The following key sequences are interpreted as described:

Press the ‘X’ key followed by the ‘C’ key.
Press the ‘X’ key while holding the ‘Control’ key, followed by the ‘C’ key.
Type ‘2’ while holding the ‘Control’ key.
Press the ‘@’ key while holding the ‘Control’ key.
Press the space bar while holding the ‘Shift’ key.
Press the ‘J’ key while holding both the ‘Control’ and ‘Alt’ keys.
Exactly the same as above.
Press the ‘J’ key while holding all of ‘Control’, ‘Alt’, and ‘Shift’ keys.

Special characters


Do nothing. This pseudo-key is useful for disabling a specific builtin mapping. For example, :map <C-n> <Nop> will prevent <C-n> from doing anything.


Pass the events consumed by the last executed mapping through to Firefox.


Expand to a line terminator in a key mapping. An Ex command in the {rhs} of a mapping requires a line terminator after it so that it is executed when the mapping is expanded. <CR> should be used for this purpose.


A pseudo-key which expands to the value of the 'mapleader' option. For example, by default,

:map <Leader>h :echo Hello<CR>

works like

:map \h :echo Hello<CR>

but after

:set mapleader=,

it works like

:map ,h :echo Hello<CR>


In addition to basic mappings, Pentadactyl can also automatically replace whole words after they've been typed. These shortcuts are known as abbreviations, and are most often useful for correcting spelling of commonly mistyped words, as well as shortening the typing of oft-typed but long words or phrases. There are three basic types of abbreviations, defined by the types of characters they contain,

For the purposes of abbreviations, keyword characters include all non-whitespace characters except for single or double quotation marks. Abbreviations are expanded as soon as any non-keyword character, or the key c_<C-]>, is typed.

:ab[breviate] [-group={group}] [-js] {lhs} {rhs}
:ab[breviate] [-group={group}] {lhs}
:ab[breviate] [-group={group}]

Abbreviate {lhs} to {rhs}. If only {lhs} is given, list all abbreviations that start with {lhs}. If no arguments are given, list all abbreviations.

If the -javascript (short names -js, -j) option is given, {lhs} is expanded to the value returned by the JavaScript code {rhs}. The code is evaluated with the variable editor set to the editable element that the abbreviation is currently being expanded in. The code should not make any changes to the contents of the editor.

If {group} is specified then abbreviations are created or listed for the given group.

:ca[bbreviate] {lhs} {rhs}
:ca[bbreviate] {lhs}

Abbreviate a key sequence for Command Line mode. Same as :ab[breviate], but for Command Line mode only.

:ia[bbreviate] {lhs} {rhs}
:ia[bbreviate] {lhs}

Abbreviate a key sequence for Insert mode. Same as :ab[breviate], but for Insert mode only.

:una[bbreviate] {lhs}

Remove an abbreviation. With [!], remove all abbreviations.

:cuna[bbreviate] {lhs}

Remove abbreviation(s) for Command Line mode. Same as :una[bbreviate], but for Command Line mode only.

:iuna[bbreviate] {lhs}

Remove abbreviation(s) for Insert mode. Same as :una[bbreviate] but for Insert mode only.

User-defined commands

Defining new commands is perhaps the most straightforward way of repeating commonly used actions. User-defined commands may be entered from the command line or scripts exactly like standard commands, and may similarly accept arguments, options, counts, and [!]s, as well as provide command-line completion. These commands may be defined as either ordinary, macro-interpolated Ex commands, or otherwise as plain JavaScript statements.


List all user-defined commands.

:com[mand] [cmd]

List all user-defined commands that start with [cmd]. Commands are partitioned into groups.

:com[mand][!] [{options}…] {cmd} {rep}

Define a new user command. The name of the command is {cmd} and its replacement text is {rep}. If a command with this name already exists, an error is reported unless [!] is specified, in which case the command is redefined. Unlike Vim, the command may start with a lowercase letter. {cmd} may also be multiple alternative command names separated by commas.

The new command is usually defined by a string to be executed as an Ex command. In this case, before execution, strings of the form <{var}> are interpolated as described below, in order to insert arguments, options, and the like. If the -javascript (short name -js) flag is present, the command is executed as JavaScript, and the arguments are present as variables in its scope instead, and no interpolation is performed.

The command's behavior can be altered by providing options when the command is defined.


The -group flag (short name: -g) can be used to assign this command to a specific group. When listing commands this limits the output to the specified group.

Argument handling

By default, user commands accept no arguments. This can be changed by specifying the -nargs option.

The valid values are:

No arguments are allowed (default)
One argument is allowed
Zero or more arguments are allowed
Zero or one argument is allowed
One or more arguments are allowed

Argument completion

Completion for arguments to user-defined commands is not available by default. Completion can be enabled by specifying one of the following arguments to the -complete option when defining the command.

alternate author style sheets
character sets
color schemes
Ex commands
Firefox dialogs
environment variables
autocommand events
installed extensions
help tags
highlight groups
browsing history
JavaScript expressions
named macros
user mappings
local page marks
menu items
Pentadactyl options
Firefox preferences
quick marks
runtime paths
search engines and keywords
shell commands
sidebar panels
user commands
custom completion, provided by {thing}

Custom completion

Custom completion can be provided by specifying the custom,{thing} argument to -complete. If {thing} evaluates to a function (i.e., it is a variable holding a function value, or a string containing the definition itself), it is called with two arguments: a completion context, and an object describing the command's arguments. It should set the context's completions property to the list of completion results. Other influential properties include title, sort, anchored, and filters, which are documented in the source code.

completions is a two-dimensional array of the form: [[val1, description1], [val2, description2], …]

Otherwise {thing} should evaluate to an array of the same form as the completions property of the context object.


:command foo -nargs=? -complete custom,
    \ function (context) context.completions = [["val1", "description1"], ["val2", "description2"]]
    \ :echo Useless  + <q-args>

:command foo -nargs=?
    \ -complete custom,[["val1", "description1"], ["val2", "description2"]]
    \ :echo Same as above but simpler  + <q-args>

Count handling

By default, user commands do not accept a count. Use the -count option if you'd like to have a count passed to your user command. This will then be available for expansion as <count> in the replacement.

Special cases

By default, a user command does not have a special version, i.e. a version executed with the ! modifier. Providing the -bang option will enable this and <bang> will be available in the replacement.

Command description

The command's description text can be set with -description. Otherwise it will default to "User-defined command".

Replacement text

The replacement text {rep} is scanned for macro-strings and these are replaced with values from the user-entered command line. The resulting string is then executed as an Ex command.

In addition to the standard parameters listed in macro-string, the following parameters are available:

The command arguments exactly as supplied
Any supplied count, e.g. 5
! if the command was executed with the ! modifier
:delc[ommand] {cmd}

Delete the user-defined command {cmd}. With [!], delete all user commands.


Add a :Google command to search via google:

:command -nargs=* Google open google <args>