Skip to content

Keyboard mappings

Nils Martel edited this page Aug 14, 2019 · 24 revisions

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 between the brackets of Some, which is the one to use in the key property of the mapping
  • The boolean properties in ModifiersState, which indicate which modifiers to add in the mods property of the mapping (these can be concatenated using the | character)

The value for the chars property of each entry in key_bindings: can be any text string and supports hexadecimal 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" }

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: "open", args: ["~/.config/alacritty/alacritty.yml"]}     }
  - { key: N,         mods: Command,      action: SpawnNewInstance       }
  - { key: Space,     mods: Alt,          chars: " "                     }

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"                        }

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: "\\"                           }

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: "\\"                      }

Tmux workaround

Launching tmux as the default shell in alacritty with the -u flag might bring back unicode symbols. In alacritty.yml:

shell:
    program: /usr/local/bin/tmux
    args:
     - -u # force UTF-8 in tmux
You can’t perform that action at this time.