qmk-firmware/docs/keycodes.md

32 KiB

Keycodes Overview

When defining a keymap each key needs a valid key definition. This page documents the symbols that correspond to keycodes that are available to you in QMK.

This is a reference only. Each group of keys links to the page documenting their functionality in more detail.

Basic Keycodes

Key Aliases Description
KC_1 1 and !
KC_2 2 and @
KC_3 3 and #
KC_4 4 and $
KC_5 5 and %
KC_6 6 and ^
KC_7 7 and &
KC_8 8 and *
KC_9 9 and (
KC_0 0 and )
KC_F1
KC_F2
KC_F3
KC_F4
KC_F5
KC_F6
KC_F7
KC_F8
KC_F9
KC_F10
KC_F11
KC_F12
KC_F13
KC_F14
KC_F15
KC_F16
KC_F17
KC_F18
KC_F19
KC_F20
KC_F21
KC_F22
KC_F23
KC_F24
KC_A a and A
KC_B b and B
KC_C c and C
KC_D d and D
KC_E e and E
KC_F f and F
KC_G g and G
KC_H h and H
KC_I i and I
KC_J j and J
KC_K k and K
KC_L l and L
KC_M m and M
KC_N n and N
KC_O o and O
KC_P p and P
KC_Q q and Q
KC_R r and R
KC_S s and S
KC_T t and T
KC_U u and U
KC_V v and V
KC_W w and W
KC_X x and X
KC_Y y and Y
KC_Z z and Z
KC_ENTER KC_ENT Return (Enter)
KC_ESCAPE KC_ESC Escape
KC_BSPACE KC_BSPC Delete (Backspace)
KC_TAB Tab
KC_SPACE KC_SPC Spacebar
KC_MINUS KC_MINS - and _
KC_EQUAL KC_EQL = and +
KC_LBRACKET KC_LBRC [ and {
KC_RBRACKET KC_RBRC ] and }
KC_BSLASH KC_BSLS \ and |
KC_NONUS_HASH KC_NUHS Non-US # and ~
KC_NONUS_BSLASH KC_NUBS Non-US \ and |
KC_INT1 KC_RO JIS \ and |
KC_INT2 KC_KANA JIS Katakana/Hiragana
KC_INT3 KC_JYEN JIS ¥
KC_SCOLON KC_SCLN ; and :
KC_QUOTE KC_QUOT ' and "
KC_GRAVE KC_GRV ` and ~
KC_COMMA KC_COMM , and <
KC_DOT . and >
KC_SLASH KC_SLSH / and ?
KC_CAPSLOCK KC_CAPS Caps Lock
KC_LCTRL KC_LCTL Left Control
KC_LSHIFT KC_LSFT Left Shift
KC_LALT Left Alt
KC_LGUI KC_LCMD, KC_LWIN Left GUI (Windows/Command/Meta key)
KC_RCTRL KC_RCTL Right Control
KC_RSHIFT KC_RSFT Right Shift
KC_RALT Right Alt
KC_RGUI KC_RCMD, KC_RWIN Right GUI (Windows/Command/Meta key)
KC_LOCKING_CAPS KC_LCAP Locking Caps Lock
KC_LOCKING_NUM KC_LNUM Locking Num Lock
KC_LOCKING_SCROLL KC_LSCR Locking Scroll Lock
KC_INT4 KC_HENK JIS Henkan
KC_INT5 KC_MHEN JIS Muhenkan
KC_PSCREEN KC_PSCR Print Screen
KC_SCROLLLOCK KC_SLCK Scroll Lock
KC_PAUSE KC_PAUS Pause
KC_INSERT KC_INS Insert
KC_HOME Home
KC_PGUP Page Up
KC_DELETE KC_DEL Forward Delete
KC_END End
KC_PGDOWN KC_PGDN Page Down
KC_RIGHT KC_RGHT Right Arrow
KC_LEFT Left Arrow
KC_DOWN Down Arrow
KC_UP Up Arrow
KC_APPLICATION KC_APP Application (Windows Menu Key)
KC_POWER Deprecated by MS in favor of KC_SYSTEM_POWER.
KC_EXECUTE Execute
KC_HELP Help
KC_MENU Menu
KC_SELECT Select
KC_AGAIN Again
KC_UNDO Undo
KC_CUT Cut
KC_COPY Copy
KC_PASTE Paste
KC_FIND Find
KC_ALT_ERASE Alternate Erase
KC_SYSREQ SysReq/Attention
KC_CANCEL Cancel
KC_CLEAR Clear
KC_PRIOR Prior
KC_RETURN Return
KC_SEPARATOR Separator
KC_OUT Out
KC_OPER Oper
KC_CLEAR_AGAIN Clear/Again
KC_CRSEL CrSel/Props
KC_EXSEL ExSel
KC_SYSTEM_POWER KC_PWR System Power Down. Recommended over KC_POWER.
KC_SYSTEM_SLEEP KC_SLEP System Sleep
KC_SYSTEM_WAKE KC_WAKE System Wake
KC_MAIL KC_MAIL
KC_CALCULATOR KC_CALC
KC_MY_COMPUTER KC_MYCM
KC_WWW_SEARCH KC_WSCH
KC_WWW_HOME KC_WHOM
KC_WWW_BACK KC_WBAK
KC_WWW_FORWARD KC_WFWD
KC_WWW_STOP KC_WSTP
KC_WWW_REFRESH KC_WREF
KC_WWW_FAVORITES KC_WFAV
KC_STOP Stop
KC__MUTE Mute (macOS)
KC__VOLUP Volume Up (macOS)
KC__VOLDOWN Volume Down (macOS)
KC_AUDIO_MUTE KC_MUTE Mute (Windows/macOS/Linux)
KC_AUDIO_VOL_UP KC_VOLU Volume Up (Windows/macOS/Linux)
KC_AUDIO_VOL_DOWN KC_VOLD Volume Down (Windows/macOS/Linux)
KC_MEDIA_NEXT_TRACK KC_MNXT Next Track (Windows)
KC_MEDIA_PREV_TRACK KC_MPRV Previous Track (Windows)
KC_MEDIA_FAST_FORWARD KC_MFFD Next Track (macOS)
KC_MEDIA_REWIND KC_MRWD Previous Track (macOS)
KC_MEDIA_STOP KC_MSTP Stop Track
KC_MEDIA_PLAY_PAUSE KC_MPLY Play/Pause Track
KC_MEDIA_SELECT KC_MSEL
KC_NUMLOCK KC_NLCK Keypad Num Lock and Clear
KC_KP_SLASH KC_PSLS Keypad /
KC_KP_ASTERISK KC_PAST Keypad *
KC_KP_MINUS KC_PMNS Keypad -
KC_KP_PLUS KC_PPLS Keypad +
KC_KP_ENTER KC_PENT Keypad Enter
KC_KP_1 KC_P1 Keypad 1 and End
KC_KP_2 KC_P2 Keypad 2 and Down Arrow
KC_KP_3 KC_P3 Keypad 3 and Page Down
KC_KP_4 KC_P4 Keypad 4 and Left Arrow
KC_KP_5 KC_P5 Keypad 5
KC_KP_6 KC_P6 Keypad 6 and Right Arrow
KC_KP_7 KC_P7 Keypad 7 and Home
KC_KP_8 KC_P8 Keypad 8 and Up Arrow
KC_KP_9 KC_P9 Keypad 9 and Page Up
KC_KP_0 KC_P0 Keypad 0 and Insert
KC_KP_DOT KC_PDOT Keypad . and Delete
KC_KP_EQUAL KC_PEQL Keypad =
KC_KP_COMMA KC_PCMM Keypad ,
KC_KP_EQUAL_AS400 Keypad = on AS/400 keyboards
KC_NO Ignore this key (NOOP)
KC_TRANSPARENT KC_TRNS Use the next lowest non-transparent key

Mouse Keys

Key Aliases Description
KC_MS_UP KC_MS_U Mouse Cursor Up
KC_MS_DOWN KC_MS_D Mouse Cursor Down
KC_MS_LEFT KC_MS_L Mouse Cursor Left
KC_MS_RIGHT KC_MS_R Mouse Cursor Right
KC_MS_BTN1 KC_BTN1 Mouse Button 1
KC_MS_BTN2 KC_BTN2 Mouse Button 2
KC_MS_BTN3 KC_BTN3 Mouse Button 3
KC_MS_BTN4 KC_BTN4 Mouse Button 4
KC_MS_BTN5 KC_BTN5 Mouse Button 5
KC_MS_WH_UP KC_WH_U Mouse Wheel Up
KC_MS_WH_DOWN KC_WH_D Mouse Wheel Down
KC_MS_WH_LEFT KC_WH_L Mouse Wheel Left
KC_MS_WH_RIGHT KC_WH_R Mouse Wheel Right
KC_MS_ACCEL0 KC_ACL0 Set mouse acceleration to 0
KC_MS_ACCEL1 KC_ACL1 Set mouse acceleration to 1
KC_MS_ACCEL2 KC_ACL2 Set mouse acceleration to 2

Quantum Keycodes

Key Aliases Description
RESET Put the keyboard into DFU mode for flashing
DEBUG Toggle debug mode
KC_GESC GRAVE_ESC Escape when tapped, ` when pressed with Shift or GUI
KC_LSPO Left Shift when held, ( when tapped
KC_RSPC Right Shift when held, ) when tapped
KC_LEAD The Leader key
KC_LOCK The Lock key
FUNC(n) F(n) Call fn_action(n) (deprecated)
M(n) Call macro n
MACROTAP(n) Macro-tap n idk FIXME

Bootmagic

Key Aliases Description
MAGIC_SWAP_CONTROL_CAPSLOCK Swap Caps Lock and Left Control
MAGIC_CAPSLOCK_TO_CONTROL Treat Caps Lock as Control
MAGIC_SWAP_LALT_LGUI Swap Left Alt and GUI
MAGIC_SWAP_RALT_RGUI Swap Right Alt and GUI
MAGIC_NO_GUI Disable the GUI key
MAGIC_SWAP_GRAVE_ESC Swap ` and Escape
MAGIC_SWAP_BACKSLASH_BACKSPACE Swap \ and Backspace
MAGIC_HOST_NKRO Force NKRO on
MAGIC_SWAP_ALT_GUI AG_SWAP Swap Alt and GUI on both sides
MAGIC_UNSWAP_CONTROL_CAPSLOCK Unswap Caps Lock and Left Control
MAGIC_UNCAPSLOCK_TO_CONTROL Stop treating Caps Lock as Control
MAGIC_UNSWAP_LALT_LGUI Unswap Left Alt and GUI
MAGIC_UNSWAP_RALT_RGUI Unswap Right Alt and GUI
MAGIC_UNNO_GUI Enable the GUI key
MAGIC_UNSWAP_GRAVE_ESC Unswap ` and Escape
MAGIC_UNSWAP_BACKSLASH_BACKSPACE Unswap \ and Backspace
MAGIC_UNHOST_NKRO Force NKRO off
MAGIC_UNSWAP_ALT_GUI AG_NORM Unswap Alt and GUI on both sides
MAGIC_TOGGLE_NKRO Turn NKRO on or off

Backlighting

Key Description
BL_TOGG Turn the backlight on or off
BL_STEP Cycle through backlight levels
BL_ON Set the backlight to max brightness
BL_OFF Turn the backlight off
BL_INC Increase the backlight level
BL_DEC Decrease the backlight level
BL_BRTG Toggle backlight breathing

RGB Lighting

Key Aliases Description
RGB_TOG Toggle RGB lighting on or off
RGB_MODE_FORWARD RGB_MOD Cycle through modes, reverse direction when Shift is held
RGB_MODE_REVERSE RGB_RMOD Cycle through modes in reverse, forward direction when Shift is held
RGB_HUI Increase hue
RGB_HUD Decrease hue
RGB_SAI Increase saturation
RGB_SAD Decrease saturation
RGB_VAI Increase value (brightness)
RGB_VAD Decrease value (brightness)
RGB_MODE_PLAIN RGB_M_P Static (no animation) mode
RGB_MODE_BREATHE RGB_M_B Breathing animation mode
RGB_MODE_RAINBOW RGB_M_R Rainbow animation mode
RGB_MODE_SWIRL RGB_M_SW Swirl animation mode
RGB_MODE_SNAKE RGB_M_SN Snake animation mode
RGB_MODE_KNIGHT RGB_M_K "Knight Rider" animation mode
RGB_MODE_XMAS RGB_M_X Christmas animation mode
RGB_MODE_GRADIENT RGB_M_G Static gradient animation mode

Thermal Printer

Key Description
PRINT_ON Start printing everything the user types
PRINT_OFF Stop printing everything the user types

Bluetooth

Key Description
OUT_AUTO Automatically switch between USB and Bluetooth
OUT_USB USB only
OUT_BT Bluetooth only

Modifiers

Key Aliases Description
KC_HYPR Hold Left Control, Shift, Alt and GUI
KC_MEH Hold Left Control, Shift and Alt
LCTL(kc) Hold Left Control and press kc
LSFT(kc) S(kc) Hold Left Shift and press kc
LALT(kc) Hold Left Alt and press kc
LGUI(kc) LCMD(kc), LWIN(kc) Hold Left GUI and press kc
RCTL(kc) Hold Right Control and press kc
RSFT(kc) Hold Right Shift and press kc
RALT(kc) Hold Right Alt and press kc
RGUI(kc) RCMD(kc), LWIN(kc) Hold Right GUI and press kc
HYPR(kc) Hold Left Control, Shift, Alt and GUI and press kc
MEH(kc) Hold Left Control, Shift and Alt and press kc
LCAG(kc) Hold Left Control, Alt and GUI and press kc
ALTG(kc) Hold Right Control and Alt and press kc
SGUI(kc) SCMD(kc), SWIN(kc) Hold Left Shift and GUI and press kc
LCA(kc) Hold Left Control and Alt and press kc

Mod-Tap Keys

Key Aliases Description
LCTL_T(kc) CTL_T(kc) Left Control when held, kc when tapped
RCTL_T(kc) Right Control when held, kc when tapped
LSFT_T(kc) SFT_T(kc) Left Shift when held, kc when tapped
RSFT_T(kc) Right Shift when held, kc when tapped
LALT_T(kc) ALT_T(kc) Left Alt when held, kc when tapped
RALT_T(kc) ALGR_T(kc) Right Alt when held, kc when tapped
LGUI_T(kc) LCMD_T(kc), RWIN_T(kc), GUI_T(kc) Left GUI when held, kc when tapped
RGUI_T(kc) RCMD_T(kc), RWIN_T(kc) Right GUI when held, kc when tapped
C_S_T(kc) Left Control and Shift when held, kc when tapped
MEH_T(kc) Left Control, Shift and Alt when held, kc when tapped
LCAG_T(kc) Left Control, Alt and GUI when held, kc when tapped
RCAG_T(kc) Right Control, Alt and GUI when held, kc when tapped
ALL_T(kc) Left Control, Shift, Alt and GUI when held, kc when tapped - more info here
SCMD_T(kc) SWIN_T(kc) Left Shift and GUI when held, kc when tapped
LCA_T(kc) Left Control and Alt when held, kc when tapped

US ANSI Shifted Keys

Key Aliases Description
KC_TILDE KC_TILD ~
KC_EXCLAIM KC_EXLM !
KC_AT @
KC_HASH #
KC_DOLLAR KC_DLR $
KC_PERCENT KC_PERC %
KC_CIRCUMFLEX KC_CIRC ^
KC_AMPERSAND KC_AMPR &
KC_ASTERISK KC_ASTR *
KC_LEFT_PAREN KC_LPRN (
KC_RIGHT_PAREN KC_RPRN )
KC_UNDERSCORE KC_UNDS _
KC_PLUS +
KC_LEFT_CURLY_BRACE KC_LCBR {
KC_RIGHT_CURLY_BRACE KC_RCBR }
KC_PIPE |
KC_COLON KC_COLN :
KC_DOUBLE_QUOTE KC_DQT/KC_DQUO "
KC_LEFT_ANGLE_BRACKET KC_LT/KC_LABK <
KC_RIGHT_ANGLE_BRACKET KC_GT/KC_RABK >
KC_QUESTION KC_QUES ?

Switching and Toggling Layers

Key Description
LT(layer, kc) Turn on layer when held, kc when tapped
TO(layer) Turn on layer when pressed
MO(layer) Momentarily turn on layer when pressed (requires KC_TRNS on destination layer)
DF(layer) Set the base (default) layer
TG(layer) Toggle layer on or off
TT(layer) Tap toggle? idk FIXME

One Shot Keys

Key Description
OSM(mod) Hold mod for one keypress
OSL(layer) Switch to layer for one keypress

Unicode Support

Key Aliases
UNICODE(n) UC(n) Send Unicode character n
X(n) Send Unicode character n via a different method

Swap Hands

Key Description
SH_T(key) Sends key with a tap; momentary swap when held.
SW_ON Turns on swapping and leaves it on.
SW_OFF Turn off swapping and leaves it off. Good for returning to a known state.
SH_MON Swaps hands when pressed, returns to normal when released (momentary).
SH_MOFF Momentarily turns off swap.
SH_TG Toggles swap on and off with every key press.
SH_TT Toggles with a tap; momentary when held.