{"id":134575,"date":"2021-03-09T08:38:23","date_gmt":"2021-03-09T08:38:23","guid":{"rendered":"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/packages\/packages-keycodes\/"},"modified":"2026-09-16T08:04:10","modified_gmt":"2026-09-16T08:04:10","slug":"packages-keycodes","status":"publish","type":"blocks-handbook","link":"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/packages\/packages-keycodes\/","title":{"rendered":"@wordpress\/keycodes"},"content":{"rendered":"<p>Keycodes utilities for WordPress, used to check the key pressed in events like <code>onKeyDown<\/code>. Contains keycodes constants for keyboard keys like <code>DOWN<\/code>, <code>UP<\/code>, <code>ENTER<\/code>, etc.<\/p>\n<h2>Installation<\/h2>\n<p>Install the module<\/p>\n<pre><code class=\"language-bash\">npm install @wordpress\/keycodes --save\n<\/code><\/pre>\n<p><em>This package assumes that your code will run in an <strong>ES2015+<\/strong> environment. If you&#8217;re using an environment that has limited or no support for such language features and APIs, you should include <a href=\"https:\/\/github.com\/WordPress\/gutenberg\/tree\/HEAD\/packages\/babel-preset-default#polyfill\">the polyfill shipped in <code>@wordpress\/babel-preset-default<\/code><\/a> in your code.<\/em><\/p>\n<h2>Usage<\/h2>\n<p>Check which key was used in an <code>onKeyDown<\/code> event:<\/p>\n<pre><code class=\"language-js\">import { DOWN, ENTER } from '@wordpress\/keycodes';\n\n\/\/ [...]\n\nonKeyDown( event ) {\n    const { keyCode } = event;\n\n    if ( keyCode === DOWN ) {\n        alert( 'You pressed the down arrow!' );\n    } else if ( keyCode === ENTER ) {\n        alert( 'You pressed the enter key!' );\n    } else {\n        alert( 'You pressed another key.' );\n    }\n}\n<\/code><\/pre>\n<h2>API<\/h2>\n<p><!-- START TOKEN(Autogenerated API docs) --><\/p>\n<h3>ALT<\/h3>\n<p>Keycode for ALT key.<\/p>\n<h3>ariaKeyShortcut<\/h3>\n<p>An object that contains functions to get shortcuts in a format compatible with the <a href=\"https:\/\/developer.mozilla.org\/en-US\/docs\/Web\/Accessibility\/ARIA\/Reference\/Attributes\/aria-keyshortcuts\"><code>aria-keyshortcuts<\/code> HTML attribute<\/a>.<\/p>\n<p><strong>Note<\/strong>: The provided shortcut character strings (ie. not the modifiers) should follow the values specified in the <a href=\"https:\/\/www.w3.org\/TR\/uievents-key\/\">UI Events KeyboardEvent key Values spec<\/a> \u2014 for example, &#8220;Enter&#8221;, &#8220;Tab&#8221;, &#8220;ArrowRight&#8221;, &#8220;PageDown&#8221;, &#8220;Escape&#8221;, &#8220;Plus&#8221;, or &#8220;F1&#8221;. The spacebar key should be represented with the &#8220;Space&#8221; string (an exception to the UI Events KeyboardEvent key Values spec).<\/p>\n<p><em>Related<\/em><\/p>\n<ul>\n<li><a href=\"https:\/\/www.w3.org\/TR\/wai-aria-1.2\/#aria-keyshortcuts\">https:\/\/www.w3.org\/TR\/wai-aria-1.2\/#aria-keyshortcuts<\/a><\/li>\n<li><a href=\"https:\/\/developer.mozilla.org\/en-US\/docs\/Web\/Accessibility\/ARIA\/Reference\/Attributes\/aria-keyshortcuts\">https:\/\/developer.mozilla.org\/en-US\/docs\/Web\/Accessibility\/ARIA\/Reference\/Attributes\/aria-keyshortcuts<\/a><\/li>\n<li><a href=\"https:\/\/www.w3.org\/TR\/uievents-key\/\">https:\/\/www.w3.org\/TR\/uievents-key\/<\/a><\/li>\n<\/ul>\n<p><em>Usage<\/em><\/p>\n<pre><code class=\"language-js\">\/\/ Assuming macOS:\nariaKeyShortcut.primary( 'm' );\n\/\/ \"Meta+M\"\n\nariaKeyShortcut.primaryAlt( 'm' );\n\/\/ \"Meta+Alt+M\"\n\n\/\/ Assuming Windows:\nariaKeyShortcut.primary( 'm' );\n\/\/ \"Control+M\"\n\nariaKeyShortcut.primaryAlt( 'm' );\n\/\/ \"Control+Alt+M\"\n\nariaKeyShortcut.primaryShift( 'del' );\n\/\/ \"Control+Shift+Delete\"\n<\/code><\/pre>\n<h3>BACKSPACE<\/h3>\n<p>Keycode for BACKSPACE key.<\/p>\n<h3>COMMAND<\/h3>\n<p>Keycode for COMMAND\/META key.<\/p>\n<h3>CTRL<\/h3>\n<p>Keycode for CTRL key.<\/p>\n<h3>DELETE<\/h3>\n<p>Keycode for DELETE key.<\/p>\n<h3>displayShortcut<\/h3>\n<p>An object that contains functions to display shortcuts.<\/p>\n<p><em>Usage<\/em><\/p>\n<pre><code class=\"language-js\">\/\/ Assuming macOS:\ndisplayShortcut.primary( 'm' );\n\/\/ \"\u2318M\"\n<\/code><\/pre>\n<p>Keyed map of functions to display shortcuts.<\/p>\n<h3>displayShortcutList<\/h3>\n<p>Return an array of the parts of a keyboard shortcut chord for display.<\/p>\n<p><em>Usage<\/em><\/p>\n<pre><code class=\"language-js\">\/\/ Assuming macOS:\ndisplayShortcutList.primary( 'm' );\n\/\/ [ \"\u2318\", \"M\" ]\n<\/code><\/pre>\n<p>Keyed map of functions to shortcut sequences.<\/p>\n<h3>DOWN<\/h3>\n<p>Keycode for DOWN key.<\/p>\n<h3>END<\/h3>\n<p>Keycode for END key.<\/p>\n<h3>ENTER<\/h3>\n<p>Keycode for ENTER key.<\/p>\n<h3>ESCAPE<\/h3>\n<p>Keycode for ESCAPE key.<\/p>\n<h3>F10<\/h3>\n<p>Keycode for F10 key.<\/p>\n<h3>HOME<\/h3>\n<p>Keycode for HOME key.<\/p>\n<h3>isAppleOS<\/h3>\n<p>Return true if platform is MacOS.<\/p>\n<p><em>Parameters<\/em><\/p>\n<ul>\n<li><em>&#095;window<\/em> <code>Window<\/code>: window object by default; used for DI testing.<\/li>\n<\/ul>\n<p><em>Returns<\/em><\/p>\n<ul>\n<li><code>boolean<\/code>: True if MacOS; false otherwise.<\/li>\n<\/ul>\n<h3>isKeyboardEvent<\/h3>\n<p>An object that contains functions to check if a keyboard event matches a predefined shortcut combination.<\/p>\n<p><em>Usage<\/em><\/p>\n<pre><code class=\"language-js\">\/\/ Assuming an event for \u2318M key press:\nisKeyboardEvent.primary( event, 'm' );\n\/\/ true\n<\/code><\/pre>\n<p>Keyed map of functions to match events.<\/p>\n<h3>keyboardShortcut<\/h3>\n<p>An object that contains functions returning the three values used to display and describe a keyboard shortcut: its display string, its <code>aria-keyshortcuts<\/code> value and its plain-text label.<\/p>\n<p>The raw representation is not included; use <code>rawShortcut<\/code> for that.<\/p>\n<p>Use it in place of calling <code>displayShortcut<\/code>, <code>ariaKeyShortcut<\/code> and <code>shortcutAriaLabel<\/code> separately, for example to build the <code>shortcut<\/code> prop of the <code>@wordpress\/ui<\/code> components.<\/p>\n<p><em>Usage<\/em><\/p>\n<pre><code class=\"language-js\">\/\/ Assuming macOS:\nkeyboardShortcut.primaryShift( 'm' );\n\/\/ {\n\/\/   displayShortcut: \"\u21e7\u2318M\",\n\/\/   ariaKeyShortcut: \"Shift+Meta+M\",\n\/\/   label: \"Shift Command M\",\n\/\/ }\n<\/code><\/pre>\n<p>Keyed map of functions to shortcut display values.<\/p>\n<h3>LEFT<\/h3>\n<p>Keycode for LEFT key.<\/p>\n<h3>modifiers<\/h3>\n<p>Object that contains functions that return the available modifier depending on platform.<\/p>\n<p><em>Type<\/em><\/p>\n<ul>\n<li><code>WPModifierHandler&lt; WPModifier &gt;<\/code><\/li>\n<\/ul>\n<h3>PAGEDOWN<\/h3>\n<p>Keycode for PAGEDOWN key.<\/p>\n<h3>PAGEUP<\/h3>\n<p>Keycode for PAGEUP key.<\/p>\n<h3>rawShortcut<\/h3>\n<p>An object that contains functions to get raw shortcuts.<\/p>\n<p>These are intended for use with the KeyboardShortcuts.<\/p>\n<p><em>Usage<\/em><\/p>\n<pre><code class=\"language-js\">\/\/ Assuming macOS:\nrawShortcut.primary( 'm' );\n\/\/ \"meta+m\"\n<\/code><\/pre>\n<h3>RIGHT<\/h3>\n<p>Keycode for RIGHT key.<\/p>\n<h3>SHIFT<\/h3>\n<p>Keycode for SHIFT key.<\/p>\n<h3>shortcutAriaLabel<\/h3>\n<p>An object that contains functions to return an aria label for a keyboard shortcut.<\/p>\n<p><em>Usage<\/em><\/p>\n<pre><code class=\"language-js\">\/\/ Assuming macOS:\nshortcutAriaLabel.primary( '.' );\n\/\/ \"Command + Period\"\n<\/code><\/pre>\n<p>Keyed map of functions to shortcut ARIA labels.<\/p>\n<h3>SPACE<\/h3>\n<p>Keycode for SPACE key.<\/p>\n<h3>TAB<\/h3>\n<p>Keycode for TAB key.<\/p>\n<h3>UP<\/h3>\n<p>Keycode for UP key.<\/p>\n<h3>withIgnoreIMEEvents<\/h3>\n<p>A higher-order function that wraps a keyboard event handler to ensure it is not an IME event.<\/p>\n<p>In CJK languages, an IME (Input Method Editor) is used to input complex characters. During an IME composition, keyboard events (e.g. Enter or Escape) can be fired which are intended to control the IME and not the application. These events should be ignored by any application logic.<\/p>\n<p><em>Parameters<\/em><\/p>\n<ul>\n<li><em>handler<\/em> <code>( event: E ) =&gt; void<\/code>: The keyboard event handler to execute after ensuring it was not an IME event.<\/li>\n<\/ul>\n<p><em>Returns<\/em><\/p>\n<ul>\n<li>A wrapped version of the given event handler that ignores IME events.<\/li>\n<\/ul>\n<h3>ZERO<\/h3>\n<p>Keycode for ZERO key.<\/p>\n<p><!-- END TOKEN(Autogenerated API docs) --><\/p>\n<h2>Contributing to this package<\/h2>\n<p>This is an individual package that&#8217;s part of the Gutenberg project. The project is organized as a monorepo. It&#8217;s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to <a href=\"https:\/\/www.npmjs.com\/\">npm<\/a> and used by <a href=\"https:\/\/make.wordpress.org\/core\/\">WordPress<\/a> as well as other software projects.<\/p>\n<p>To find out more about contributing to this package or Gutenberg as a whole, please read the project&#8217;s main <a href=\"https:\/\/github.com\/WordPress\/gutenberg\/tree\/HEAD\/CONTRIBUTING.md\">contributor guide<\/a>.<\/p>\n","protected":false},"author":0,"featured_media":0,"parent":134521,"menu_order":431,"template":"","meta":{"footnotes":""},"class_list":["post-134575","blocks-handbook","type-blocks-handbook","status-publish","hentry","type-handbook"],"revision_note":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/blocks-handbook\/134575","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/blocks-handbook"}],"about":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/types\/blocks-handbook"}],"version-history":[{"count":19,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/blocks-handbook\/134575\/revisions"}],"predecessor-version":[{"id":184690,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/blocks-handbook\/134575\/revisions\/184690"}],"up":[{"embeddable":true,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/blocks-handbook\/134521"}],"wp:attachment":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/media?parent=134575"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}