Currently trying to setup a custom keyboard layout, with separate layers for right and left option keys.

Basically, mimic the same behavior we have on other operating systems with Alt and AltGr.

I would expect this to be possible since the operating system does seem to be able to differentiate those keys (as shown when playing with configuration of programs such as skhd, karabiner-elements, etc). I do not consider those to be clean solutions, and would prefer avoiding them if possible, because :

  • having a hotkey daemon transforming inputs on the fly before they are fed to a keyboard layout is a ton more complexity and work than directly doing everything at the keyboard layout level
  • you still lose several layers with this setup

So, tried various setups (like using ukulele), but no tool manipulating keyboard layouts directly seems to be able to differentiate those keys.

Digging a bit deeper, I found an apple specification for keyboard layouts (apparently not up-to-date, but couldn't find any newer)

This seems to allow me to do exactly what I want to do, with the following keywords :

  • option: Left option key
  • rightOption: Right option key
  • anyOption: Either right or left option key

Except ... it doesn't work.

Here is a minimalist keyboard layout example :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE keyboard SYSTEM "file://localhost/System/Library/DTDs/KeyboardLayout.dtd">
<keyboard group="0" id="0" name="test 7" maxout="1">
    <layout first="0" last="17" modifiers="commonModifiers" mapSet="ANSI" />

  <modifierMap id="commonModifiers" defaultIndex="3">
    <keyMapSelect mapIndex="0">
      <modifier keys="" />
    <keyMapSelect mapIndex="1">
      <modifier keys="option" />
    <keyMapSelect mapIndex="2">
      <modifier keys="rightOption" />
    <keyMapSelect mapIndex="3">
      <modifier keys="" />

  <keyMapSet id="ANSI">

    <keyMap index="0">
      <key code="12"  output="0" />

    <keyMap index="1">
      <key code="12"  output="1" />

    <keyMap index="2">
      <key code="12"  output="2" />

    <keyMap index="3">
      <key code="12"  output="3" />



Putting this in a .keylayout file in ~/Library/Keyboard Layouts/, selecting it, here is the behavior I get :

  • q : sends "1" instead of "0"
  • left opt + q : sends "3" instead of "1"
  • right opt + q : sends "3" instead of "2"

... yeah, I'm confused as well.

Please also note that :

  • putting any random string instead of one of those keywords makes the keyboard not compile, meaning the keywords are actually recognized
  • anyOption seems to be working correctly (like, setting it instead of rightOption in the example above makes both opt keys return "2")

So far, my best guess is that option and rightOption are still considered valid keywords, but ignored.

Does anybody know if there is a way to make those keywords work as expected ? Is my syntax incorrect ?

Otherwise, is there any other way to do this ? Like, another (newer or older) keyboard definition format ?

It seems the "bundle" format mentioned in this doc is just a .keylaout file with extra metadata.

  • What is the actual purpose of this, if achievable? As Macs with a right Opt also have a right Ctrl, I'm not seeing the result:effort ratio as being particularly profitable.
    – Tetsujin
    Nov 27, 2021 at 17:10
  • 1
    @Tetsujin my current keyboard layout has many extra chars accessible on the AltGr layer, and nothing on the Alt layer. I use the Alt layer to control tmux, and am pretty happy to have an entire layer doing nothing by default to use for custom mappings.
    – toadjaune
    Nov 27, 2021 at 22:45
  • How did you make a keyboard layout with AltGr characters? Or do you mean you made one for Windows? Do you just mean these - i.stack.imgur.com/5JFQH.png - or do have have an entire custom map?
    – Tetsujin
    Nov 28, 2021 at 8:59
  • Have you looked into Karabiner-Elements? Nov 28, 2021 at 17:00


You must log in to answer this question.

Browse other questions tagged .