Mac OS X Keybinding Key Syntax

By Xah Lee. Date: . Last updated: .

This page shows the key syntax for creating keybindings on Mac OS X.

[see macOS: Create Custom Keyboard Layout]

You can define keys with any of {⌘ command, ⌥ option, Ctrl, Shift} keys held down, or any combination of them, or single keys such as {b, F2}.

Normal Key Syntax

A normal key on the keyboard is simply represented by its character. Like this:

{
"." = ("insertText:", "a");
"2" = ("insertText:", "a");
"b" = ("insertText:", "a");
"B" = ("insertText:", "a");
"!" = ("insertText:", "a");
}

With the above, typing any of the chars on the left will insert “a”.

Modifier Combination Key Syntax; Numerical Keypad Keys

To represent a combination keypress such as ⌘ command+b, prefix a @ in front of the character, like this: "@b". Here's a table showing the prefixes for various modifier keys:

PrefixMeaning
~⌥ Option key
$⇧ Shift key
^^ Control key
@⌘ Command key
#keys on number pad

Example:

{
"@b" = ("insertText:", "Cmd+b pressed.");
"~a" = ("insertText:", "Opt+a pressed.");
"^b" = ("insertText:", "Crtl+b pressed.");
"^@a" = ("insertText:", "Ctrl+Cmd+a pressed.");
"^~a" = ("insertText:", "Crtl+Opt+a pressed.");
"#2" = ("insertText:", "2 on the number keypad pressed.");
}

Note: key combination with the ⌘ command key usually won't work. For example, you cannot override ⌘ command+c for Copy, nor for any standard keys such as Cut (x), Paste (v), Undo (z), Select All (a), Open (o), Close (w), Print (p), …. Some combination with the Option key also won't work. For example, "~n" = …; will not work, because you cannot override ⌥ option+n, which is a prefix “~” for entering combo-chars, such as ñ, ã, etc.

Note: for some keypresses involving the Shift key, such as typing “A” or “!”, do not use $a or $1; just use the characters themselves like A or !. Use the dollar sign for special keys, for example: $\UF72C for Shift+PageUp.

Function Keys

Here are some standard function keys and their key code designated by the Cocoa Text System:

KeyCode
⎋ Esc\U001B
⌫ Backspace/delete †\U007F
⇥ Tab\U0009
↩ Enter/Return †\U000D
⌤ Enter (on numberpad) †\U0003
↑ up arrow\UF700
↓ down arrow\UF701
← left arrow\UF702
→ right arrow\UF703
↖ Home\UF729
↘ End\UF72B
⇞ Page Up\UF72C
⇟ Page Down\UF72D
Insert †\UF727
⌦ Delete (forward delete)\UF728
⌧ NumLock/clear †\UF739
F1\UF704
F2\UF705
F3\UF706
F4\UF707
F5\UF708
F6\UF709
F7\UF70A
F8\UF70B
F9\UF70C
F10\UF70D
F11\UF70E
F12\UF71F
F13\UF710
F14\UF711
F15\UF712
⎙ PrintScreen\UF72E
ScrollLock\UF72F
Pause\UF730
SysReq\UF731
Break\UF732
Reset\UF733
Stop\UF734
Menu\UF735
↶ Undo\UF743
↷ Redo\UF744
Find\UF745
Help\UF746

† For computer keyboard users, note that Windows and Apple keyboard have some differences. Some are just differences in key labeling, but some are not. See: Difference Between Apple and Microsoft keyboards .

The keycode for special key are defined in the file /System/Library/Frameworks/AppKit.framework/Versions/C/Headers/NSEvent.h. Here's a local copy from Mac OS X 10.4.11: NSEvent.h

Here is a sample code involving a special key.

{
"\UF70B" = ("insertText:", "F8 key pressed");
"^\UF70B" = ("insertText:", "Ctrl+F8 pressed");
"@\UF70B" = ("insertText:", "Cmd+F8 pressed");
"~\UF70B" = ("insertText:", "Otp+F8 pressed");
}

Key Sequence

You can also set a sequence of keys. For example, if you want Ctrl+x Ctrl+s to be Save, do this:

"^x" = {"^s"  = "save:";};

For action code, see: Mac OS X Keybinding Action Code

Back to Creating Keyboard Layout in Mac OS X