Keyboard mappings - alacritty/alacritty Wiki

Original URL: https://github.com/alacritty/alacritty/wiki/Keyboard-mappings

Table of Contents

Syntax documentation

While this includes some helpful examples and tips for changing keyboard mappings in Alacritty, the full syntax is documented in the default configuration file.

How to create a mapping

  1. Follow the installation guide to set up alacritty
  2. Run alacritty using alacritty --print-events (use ./target/release/osx/Alacritty.app/Contents/MacOS/alacritty on Mac OS)

At this point, Alacritty should log events pairs like this:

glutin event: WindowEvent { window_id: WindowId(Id(140237741461568)), event: KeyboardInput { device_id: DeviceId(DeviceId), input: KeyboardInput { scancode: 33, state: Pressed, virtual_keycode: Some(LBracket), modifiers: ModifiersState { shift: false, ctrl: false, alt: true, logo: false } } } }
glutin event: WindowEvent { window_id: WindowId(Id(140237741461568)), event: ReceivedCharacter('[') }

We're interested in:

The value for the chars property of each entry in key_bindings: can be any text string and supports both hexadecimal (\xNN) and unicode (\uNNNN) escapes:

  # Insert the `[` character
  - { key: LBracket, mods: Alt, chars: "[" }
  # Send the Ctrl+C control using its hex value...
  - { key: T, mods: Control|Shift, chars: "\x03" }
  # ... or using its unicode value
  - { key: T, mods: Control|Shift, chars: "\u0003" }

The virtual_keycode is None

If Alacritty is not able to find the correct keycode for the pressed key, it might be None. However, it's still possible to map the key yourself by using its scancode.

The scancode is also printed in the output of --print-events and can be used directly in the key field of a mapping:

  - { key: 33, mods: Alt, chars: "[" }

General Quality of Life Improvements

MacOS

  - { key: Comma,     mods: Command,      command:
      {program: "sh", args: ["-c","open ~/.config/alacritty/alacritty.yml"]}     }
  - { key: N,         mods: Command,      action: SpawnNewInstance       }
  - { key: Space,     mods: Alt,          chars: " "                     }
  - { key: Back, mods: Super, chars: "\x15" } # delete word/line
  - { key: Left,     mods: Alt,     chars: "\x1bb"                       } # one word left
  - { key: Right,    mods: Alt,     chars: "\x1bf"                       } # one word right
  - { key: Left,     mods: Command, chars: "\x1bOH",   mode: AppCursor   } # Home
  - { key: Right,    mods: Command, chars: "\x1bOF",   mode: AppCursor   } # End

Italian

Mac OS

  - { key: LBracket,    mods: Alt|Shift,      chars: "\x7B"              }
  - { key: RBracket,    mods: Alt|Shift,      chars: "\x7D"              }
  - { key: LBracket,    mods: Alt,            chars: "\x5B"              }
  - { key: RBracket,    mods: Alt,            chars: "\x5D"              }
  - { key: Semicolon,   mods: Alt,            chars: "\x40"              }
  - { key: Apostrophe,  mods: Alt,            chars: "\x23"              }
  - { key: Caret,       mods: Alt,            chars: "\x60"              }
  - { key: Key5,        mods: Alt,            chars: "\x7E"              }

Spanish

Mac OS

  - { key: Caret,    mods: Alt,     chars: "\x5C"                        }
  - { key: Key1,     mods: Alt,     chars: "|"                           }
  - { key: Key2,     mods: Alt,     chars: "@"                           }
  - { key: Key3,     mods: Alt,     chars: "#"                           }
  - { key: Key6,     mods: Alt,     chars: "¬"                           }
  - { key: LBracket, mods: Alt,     chars: "\x5B"                        }
  - { key: RBracket, mods: Alt,     chars: "\x5D"                        }
  - { key: Apostrophe,  mods: Alt,  chars: "\x7B"                        }
  - { key: Backslash,   mods: Alt,  chars: "\x7D"                        }

macOS Spanish (Spain)

Setup for macOS Spanish-Spain keyboard with ISO layout (not ANSI); big Enter key.

  # Ajustes para teclado macOS español/Spanish de España con layout ISO (no ANSI); tecla Intro grande.
  - { key: 10,        mods: Alt,    chars: "\x5c" } # barra invertida `\`
  - { key: 18,        mods: Alt,    chars: "\x7c" } # barra vertical `|`
  - { key: Key2,      mods: Alt,    chars: "@" } # arroba `@`
  - { key: Key3,      mods: Alt,    chars: "#" } # almohadilla/cardinalidad `#`
  - { key: Key6,      mods: Alt,    chars: "¬" } # negación en lógica `¬`
  - { key: 39,        mods: Alt,    chars: "{" } # abre llaves `{`
  - { key: 42,        mods: Alt,    chars: "}" } # cierra llaves `}`
  - { key: 33,        mods: Alt,    chars: "[" } # abre corchetes `[`
  - { key: 30,        mods: Alt,    chars: "]" } # cierra corchetes `]`

Swiss German

Mac OS

  - { key: Key3,     mods: Alt,           chars: "\x23"                  }
  - { key: Key5,     mods: Alt,           chars: "\x5b"                  }
  - { key: Key6,     mods: Alt,           chars: "\x5d"                  }
  - { key: Key7,     mods: Alt,           chars: "\x7c"                  }
  - { key: Key7,     mods: Shift|Alt,     chars: "\x5c"                  }
  - { key: Key8,     mods: Alt,           chars: "\x7b"                  }
  - { key: Key9,     mods: Alt,           chars: "\x7d"                  }
  - { key: Equals,                        chars: "\xb4"                  }
  - { key: Equals,   mods: Shift,         chars: "\x60"                  }
  - { key: N,        mods: Alt,           chars: "\u007E"                }
  - { key: G,        mods: Alt,           chars: "\x40"                  }

Portuguese (pt_PT)

Mac OS

  - { key: Key8,        mods: Alt|Shift,      chars: "\x7B"              }
  - { key: Key9,        mods: Alt|Shift,      chars: "\x7D"              }
  - { key: Key8,        mods: Alt,            chars: "\x5B"              }
  - { key: Key9,        mods: Alt,            chars: "\x5D"              }
  - { key: Key2,        mods: Alt,            chars: "\x40"              }

German (de_DE)

Mac OS

  - { key: Key5,     mods: Alt,        chars: "\x5b"                     }
  - { key: Key6,     mods: Alt,        chars: "\x5d"                     }
  - { key: Key7,     mods: Alt|Shift,  chars: "\x5c"                     }
  - { key: Key7,     mods: Alt,        chars: "\x7c"                     }
  - { key: Key8,     mods: Alt,        chars: "\x7b"                     }
  - { key: Key9,     mods: Alt,        chars: "\x7d"                     }
  - { key: L,        mods: Alt,        chars: "\x40"                     }

When using an german MacBookPro (15", 2019) with Touchbar, these might fail, but here's a working solution:

  - { key: 28,      mods: Alt, chars: "{" }
  - { key: 25,      mods: Alt, chars: "}" }
  - { key: 37,      mods: Alt, chars: "@" }
  - { key: 26,      mods: Alt|Shift, chars: "\\" }
  - { key: 26,      mods: Alt, chars: "|" }
  - { key: 45,      mods: Alt, chars: "~" }
  - { key: 23,      mods: Alt, chars: "[" }
  - { key: 22,      mods: Alt, chars: "]" }

For those, coming from iTerm, here's Command + Enter to ToggleFullscreen

  - { key: 36,      mods: Command, action: ToggleFullscreen }

Windows

  - { key: OEM102,   mods: Control|Alt,    chars: "|"                    }
  - { key: Q,        mods: Control|Alt,    chars: "@"                    }
  - { key: Key7,     mods: Control|Alt,    chars: "{"                    }
  - { key: Key8,     mods: Control|Alt,    chars: "["                    }
  - { key: Key9,     mods: Control|Alt,    chars: "]"                    }
  - { key: Key0,     mods: Control|Alt,    chars: "}"                    }
  - { key: Key0,     mods: Control|Alt,    chars: "}"                    }
  - { key: 12,       mods: Control|Alt,    chars: '\'                    }
  - { key: Equals,   mods: Control|Alt,    chars: '~'                    }

Swedish (sv_SE)

Mac OS

  - { key: Key1,      mods: Alt,          chars: "\xA9"                  }
  - { key: Key2,      mods: Alt,          chars: "\x40"                  }
  - { key: Key3,      mods: Alt,          chars: "\xA3"                  }
  - { key: Key4,      mods: Alt,          chars: "\x24"                  }
  - { key: Key5,      mods: Alt,          chars: "∞"                     }
  - { key: Key6,      mods: Alt,          chars: "\xA7"                  }
  - { key: Key7,      mods: Alt,          chars: "\x7C"                  }
  - { key: Key8,      mods: Alt,          chars: "\x5B"                  }
  - { key: Key9,      mods: Alt,          chars: "\x5D"                  }
  - { key: Key0,      mods: Alt,          chars: "≈"                     }
  - { key: Minus,     mods: Alt,          chars: "\xB1"                  }

## sv_SE PC Layout ('{', '}', '\' and '|' characters):
#  - { key: Key7,      mods: Alt,          chars: "\x7B"                  }
#  - { key: Key0,      mods: Alt,          chars: "\x7D"                  }
#  - { key: Minus,     mods: Alt,          chars: "\x5C"                  }
#  - { key: Grave,     mods: Alt,          chars: "\x7C"                  }
  
  - { key: Key1,      mods: Alt|Shift,    chars: "\xA1"                  }
  - { key: Key2,      mods: Alt|Shift,    chars: "”"                     }
  - { key: Key3,      mods: Alt|Shift,    chars: "\xA5"                  }
  - { key: Key4,      mods: Alt|Shift,    chars: "\x24"                  }
  - { key: Key5,      mods: Alt|Shift,    chars: "‰"                     }
  - { key: Key6,      mods: Alt|Shift,    chars: "\xB6"                  }
  - { key: Key7,      mods: Alt|Shift,    chars: "\x5C"                  }
  - { key: Key8,      mods: Alt|Shift,    chars: "\x7B"                  }
  - { key: Key9,      mods: Alt|Shift,    chars: "\x7D"                  }
  - { key: Key0,      mods: Alt|Shift,    chars: "≠"                     }
  - { key: Minus,     mods: Alt|Shift,    chars: "\xBF"                  }

# Replace the default bindings for these as the VirtualKeycodes don't match reality
  - { key: Slash,     mods: Command,      action: DecreaseFontSize       }
  - { key: Minus,     mods: Command,      action: IncreaseFontSize       }

Windows

  - { key: Key2,      mods: Control|Alt,  chars: "\x40"                  }
  - { key: Key3,      mods: Control|Alt,  chars: "\xA3"                  }
  - { key: Key4,      mods: Control|Alt,  chars: "\x24"                  }
  - { key: Key5,      mods: Control|Alt,  chars: "€"                     }
  - { key: Key7,      mods: Control|Alt,  chars: "\x7B"                  }
  - { key: Key8,      mods: Control|Alt,  chars: "\x5B"                  }
  - { key: Key9,      mods: Control|Alt,  chars: "\x5D"                  }
  - { key: Key0,      mods: Control|Alt,  chars: "\x7D"                  }
  - { key: Equals,    mods: Control|Alt,  chars: "\x5C"                  }

French (fr_FR)

Mac OS

  - { key: Equals,    mods: Command,    action: DecreaseFontSize              }
  - { key: Slash,     mods: Command,    action: IncreaseFontSize              }
  - { key: A,         mods: Command,    action: Quit                          }
  - { key: Z,         mods: Command,    action: Quit                          }
  - { key: L,         mods: Alt|Shift,  chars: "|"                            }
  - { key: Key5,      mods: Alt,        chars: "{"                            }
  - { key: Minus,     mods: Alt,        chars: "}"                            }
  - { key: Key5,      mods: Alt|Shift,  chars: "["                            }
  - { key: Minus,     mods: Alt|Shift,  chars: "]"                            }
  - { key: N,         mods: Alt,        chars: "~"                            }
  - { key: Period,    mods: Alt|Shift,  chars: "\\"                           }

Mac OS / French - PC

  - { key: 19,             mods: Alt,                       chars: "~"                     }
  - { key: 21,             mods: Alt,                       chars: "{"                     }
  - { key: 22,             mods: Alt,                       chars: "|"                     }
  - { key: 23,             mods: Alt,                       chars: "["                     }
  - { key: 24,             mods: Alt,                       chars: "}"                     }
  - { key: 25,             mods: Alt,                       chars: "^"                     }
  - { key: 26,             mods: Alt,                       chars: "`"                     }
  - { key: 27,             mods: Alt,                       chars: "]"                     }
  - { key: 28,             mods: Alt,                       chars: "\\"                    }
  - { key: 29,             mods: Alt,                       chars: "@"                     }

French (fr_CA)

Mac OS

  - { key: 10,             mods: Alt,                       chars: "|"                     }
  - { key: 19,             mods: Alt,                       chars: "~"                     }
  - { key: 24,             mods: Alt,                       chars: "¬"                     }
  - { key: 25,             mods: Alt,                       chars: "["                     }
  - { key: 26,             mods: Alt,                       chars: "{"                     }
  - { key: 28,             mods: Alt,                       chars: "}"                     }
  - { key: 29,             mods: Alt,                       chars: "]"                     }
  - { key: 30,             mods: Alt,                       chars: "~"                     }
  - { key: 33,             mods: Alt,                       chars: "`"                     }
  - { key: 41,             mods: Alt,                       chars: "°"                     }
  - { key: 43,             mods: Alt,                       chars: "<"                     }
  - { key: 47,             mods: Alt,                       chars: ">"                     }

Belgian

Mac OS

  - { key: LBracket,  mods: Alt,       chars: "{"                       }
  - { key: RBracket,  mods: Alt,       chars: "}"                       }
  - { key: LBracket,  mods: Alt|Shift, chars: "["                       }
  - { key: RBracket,  mods: Alt|Shift, chars: "]"                       }
  - { key: 37,        mods: Alt|Shift, chars: "|"                       }
  - { key: 47,        mods: Alt|Shift, chars: "\\"                      }