Command MenuReady

Command Menu allows users to navigate and use an app without touching the mouse and helps them transform into “power users” who can harness more advanced features far faster.

Open in new window

View RTL

<nord-command-menu open></nord-command-menu>

<script>
  const menu = document.querySelector("nord-command-menu")

  menu.commands = [
    {
      id: "consultation",
      title: "Start consultation",
      keywords: "command new create",
      shortcut: "Alt+KeyC",
      section: "Commands",
      handler: () => {
        alert("Start consultation")
      },
    },
    {
      id: "patient",
      title: "New patient",
      keywords: "command new create",
      shortcut: "Alt+KeyP",
      icon: "interface-add",
      section: "Commands",
      handler: () => {
        alert("New patient")
      },
    },
    {
      id: "appointment",
      title: "New appointment",
      keywords: "command new create",
      shortcut: "Alt+KeyA",
      icon: "interface-add",
      section: "Commands",
      handler: () => {
        alert("New appointment")
      },
    },
    {
      id: "invoice",
      title: "New invoice",
      keywords: "command new create",
      shortcut: "Alt+KeyI",
      icon: "interface-add",
      section: "Commands",
      handler: () => {
        alert("New invoice")
      },
    },
    {
      id: "user",
      title: "Switch user",
      keywords: "command change log sign out in",
      shortcut: "Alt+KeyU",
      icon: "user-multiple",
      section: "Commands",
      handler: () => {
        alert("Switch user")
      },
    },
    {
      id: "theme",
      keywords: "dark light mode ui",
      title: "Change theme...",
      icon: "file-picture",
      shortcut: "Alt+KeyT",
      section: "Commands",
    },
    {
      id: "Light Theme",
      keywords: "mode ui",
      title: "Change theme to Light",
      icon: "interface-mode-light",
      parent: "theme",
      handler: () => {
        alert("Change to light theme")
      },
    },
    {
      id: "Dark Theme",
      keywords: "mode ui",
      title: "Change theme to Dark",
      icon: "interface-mode-dark",
      parent: "theme",
      handler: () => {
        alert("Change to dark theme")
      },
    },
    {
      id: "dashboard",
      keywords: "sections view go to visit",
      title: "Open dashboard",
      shortcut: "Alt+Digit1",
      section: "Sections",
      handler: () => {
        alert("Open dashboard")
      },
    },
    {
      id: "payments",
      keywords: "sections view go to visit",
      title: "Open payments",
      shortcut: "Alt+Digit2",
      section: "Sections",
      handler: () => {
        alert("View payments")
      },
    },
    {
      id: "reports",
      keywords: "sections view go to visit",
      title: "Open reports",
      shortcut: "Alt+Digit3",
      section: "Sections",
      handler: () => {
        alert("Open reports")
      },
    },
    {
      id: "settings",
      keywords: "sections view go to visit",
      title: "Open settings",
      shortcut: "Alt+Digit4",
      section: "Sections",
      handler: () => {
        alert("Open settings")
      },
    },
  ]
</script>

<nord-button variant="primary">Open menu (Ctrl+K)</nord-button>
<script>
  const button = document.querySelector("nord-button")

  if (navigator.platform.indexOf("Mac") > -1) {
    button.textContent = "Open menu (⌘+K)"
  }
  button.addEventListener("click", () => {
    menu.show()
  })
</script>

<nord-command-menu open></nord-command-menu>

<script>
  const menu = document.querySelector("nord-command-menu")

  menu.commands = [
    {
      id: "consultation",
      title: "Start consultation",
      keywords: "command new create",
      shortcut: "Alt+KeyC",
      handler: () => {
        alert("Start consultation")
      },
    },
    {
      id: "patient",
      title: "New patient",
      keywords: "command new create",
      shortcut: "Alt+KeyP",
      icon: "interface-add",
      handler: () => {
        alert("New patient")
      },
    },
    {
      id: "appointment",
      title: "New appointment",
      keywords: "command new create",
      shortcut: "Alt+KeyA",
      icon: "interface-add",
      handler: () => {
        alert("New appointment")
      },
    },
    {
      id: "invoice",
      title: "New invoice",
      keywords: "command new create",
      shortcut: "Alt+KeyI",
      icon: "interface-add",
      handler: () => {
        alert("New invoice")
      },
    },
    {
      id: "user",
      title: "Switch user",
      keywords: "command change log sign out in",
      shortcut: "Alt+KeyU",
      icon: "user-multiple",
      handler: () => {
        alert("Switch user")
      },
    },
    {
      id: "theme",
      keywords: "dark light mode ui",
      title: "Change theme...",
      icon: "file-picture",
      shortcut: "Alt+KeyT",
    },
    {
      id: "dashboard",
      keywords: "sections view go to visit",
      title: "Open dashboard",
      shortcut: "Alt+Digit1",
      handler: () => {
        alert("Open dashboard")
      },
    },
    {
      id: "payments",
      keywords: "sections view go to visit",
      title: "Open payments",
      shortcut: "Alt+Digit2",
      handler: () => {
        alert("View payments")
      },
    },
    {
      id: "reports",
      keywords: "sections view go to visit",
      title: "Open reports",
      shortcut: "Alt+Digit3",
      handler: () => {
        alert("Open reports")
      },
    },
    {
      id: "settings",
      keywords: "sections view go to visit",
      title: "Open settings",
      shortcut: "Alt+Digit4",
      handler: () => {
        alert("Open settings")
      },
    },
  ]
</script>

<nord-button variant="primary">Open menu (Ctrl+K)</nord-button>
<script>
  const button = document.querySelector("nord-button")

  if (navigator.platform.indexOf("Mac") > -1) {
    button.textContent = "Open menu (⌘+K)"
  }
  button.addEventListener("click", () => {
    menu.show()
  })
</script>

<nord-command-menu></nord-command-menu>

<nord-stack direction="horizontal">
  <nord-button variant="primary">Open command menu</nord-button>
  <nord-checkbox label="Allow open?" checked></nord-checkbox>
</nord-stack>

<script>
  const menu = document.querySelector("nord-command-menu")
  const button = document.querySelector("nord-button")
  const checkbox = document.querySelector("nord-checkbox")

  menu.commands = [
    {
      id: "consultation",
      title: "Start consultation",
      keywords: "command new create",
      shortcut: "Alt+KeyC",
      section: "Commands",
      handler: () => {
        alert("Start consultation")
      },
    },
  ]

  menu.addEventListener("open", e => {
    if (!checkbox.checked) {
      e.preventDefault()
    }
  })

  button.addEventListener("click", () => {
    menu.show()
  })
</script>

<nord-command-menu open></nord-command-menu>

<script>
  const menu = document.querySelector("nord-command-menu")

  menu.commands = [
    {
      id: "theme",
      keywords: "dark light mode ui",
      title: "Change theme...",
      icon: "file-picture",
      shortcut: "Alt+KeyT",
      section: "Commands",
    },
    {
      id: "Light Theme",
      keywords: "mode ui",
      title: "Change theme to Light",
      icon: "interface-mode-light",
      parent: "theme",
      handler: () => {
        alert("Change to light theme")
      },
    },
    {
      id: "Dark Theme",
      keywords: "mode ui",
      title: "Change theme to Dark",
      icon: "interface-mode-dark",
      parent: "theme",
      handler: () => {
        alert("Change to dark theme")
      },
    },
  ]
</script>

<nord-button variant="primary">Open menu (Ctrl+K)</nord-button>
<script>
  const button = document.querySelector("nord-button")

  if (navigator.platform.indexOf("Mac") > -1) {
    button.textContent = "Open menu (⌘+K)"
  }
  button.addEventListener("click", () => {
    menu.show()
  })
</script>

<nord-command-menu open></nord-command-menu>

<script>
  const menu = document.querySelector("nord-command-menu")

  menu.commands = [
    {
      id: "consultation",
      title: "Start consultation",
      keywords: "command new create",
      shortcut: "Alt+KeyC",
      handler: () => {
        alert("Start consultation")
      },
    },
    {
      id: "patient",
      title: "New patient",
      keywords: "command new create",
      shortcut: "Alt+KeyP",
      handler: () => {
        alert("New patient")
      },
    },
    {
      id: "appointment",
      title: "New appointment",
      keywords: "command new create",
      shortcut: "Alt+KeyA",
      handler: () => {
        alert("New appointment")
      },
    },
    {
      id: "invoice",
      title: "New invoice",
      keywords: "command new create",
      shortcut: "Alt+KeyI",
      handler: () => {
        alert("New invoice")
      },
    },
    {
      id: "user",
      title: "Switch user",
      keywords: "command change log sign out in",
      shortcut: "Alt+KeyU",
      handler: () => {
        alert("Switch user")
      },
    },
    {
      id: "theme",
      keywords: "dark light mode ui",
      title: "Change theme...",
      shortcut: "Alt+KeyT",
    },
    {
      id: "dashboard",
      keywords: "sections view go to visit",
      title: "Open dashboard",
      shortcut: "Alt+Digit1",
      handler: () => {
        alert("Open dashboard")
      },
    },
    {
      id: "payments",
      keywords: "sections view go to visit",
      title: "Open payments",
      shortcut: "Alt+Digit2",
      handler: () => {
        alert("View payments")
      },
    },
    {
      id: "reports",
      keywords: "sections view go to visit",
      title: "Open reports",
      shortcut: "Alt+Digit3",
      handler: () => {
        alert("Open reports")
      },
    },
    {
      id: "settings",
      keywords: "sections view go to visit",
      title: "Open settings",
      shortcut: "Alt+Digit4",
      handler: () => {
        alert("Open settings")
      },
    },
  ]
</script>

<nord-button variant="primary">Open menu (Ctrl+K)</nord-button>
<script>
  const button = document.querySelector("nord-button")

  if (navigator.platform.indexOf("Mac") > -1) {
    button.textContent = "Open menu (⌘+K)"
  }
  button.addEventListener("click", () => {
    menu.show()
  })
</script>

Properties

Property	Attribute	Description	Type	Default
`open`	`open`	Show or hide the command menu.	`boolean`	`false`
`commands`	–	Array of commands to be included in the menu. Please see “Commands data” section for more documentation.	`Array<ICommandMenuAction>`	`[]`

Events

Event	Description	Type
`open`	The command menu was opened.	`NordEvent`
`close`	The command menu was closed.	`NordEvent`
`nord-select`	User selected a command from the menu.	`SelectEvent`

Slots

Slot name	Description
`footer`	Used to replace the default footer contents.

Methods

Method name	Parameters	Description
`show(options: { parent?: string }) => void`	`options`: allows you to open the menu filtered to a specific parent command.	Show the command menu programmatically.
`close() => void`	N/A	Close the command menu programmatically.
`toggleOpen() => void`	N/A	Toggle the open state programmatically.
`focus() => void`	N/A	Focus the command menu's input.

CSS Properties

CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.

Property	Description	Default
`--n-command-menu-inline-size`	Controls the max inline size, or width, of the command menu.	`640px`
`--n-command-menu-block-size`	Controls the max block size, or height, of the command menu.	`290px`
`--n-command-menu-block-start`	Controls the command menu offset from the block start, or top, of the screen.	`16%`

Localization

This component requires localization in a multi-lingual application. The following keys are required when registering a translation:

Key	Description
`instructions`	Instructions that offer guidance on how to use the command menu.
`inputLabel`	Accessible label given to the command menu's input.
`footerArrowKeys`	Describes what the arrow keys do.
`footerEnterKey`	Describes what the enter key does.
`footerEscapeKey`	Describes what the escape key does.
`footerBackspaceKey`	Describes what the backspace key does.
`noResults`	A message shown when there are no matching results.
`tip`	A hint tip that describes some approaches to find a command when there are no matching results.
`placeholder`	Hint text to display in the Command Menu search field.

For full localization guidelines, please see Localization documentation.

Localization Guidelines

Dependencies

This component is internally dependent on the following components:

Usage #

This section includes guidelines for designers and developers about the usage of this component in different contexts.

Do #

Use to provide global and contextual keyboard shortcuts for users.
Make command menu available everywhere. Users must be able to bring up the command menu easily.
Make command menu central. Users should be able to find global shortcuts from one location.
Make command menu omnipotent. Give users access to every possible action.
Group related commands logically under sections with the section setting.
Use Alt key as the modifier, since this is less likely to clash with existing shortcuts.

Don’t #

Don’t make command menu available only in certain views of the application.
Don’t define shortcuts such as Ctrl+C, since this will clash with the native "Copy" shortcut.
Don't create complex shortcuts, as users will struggle to remember them.
Avoid using KeyboardEvent.key for defining the shortcut keys.
Don’t use as a search field only.

Content guidelines #

Command titles should be clear, accurate and predictable. It should be possible for the user to understand what will happen when they execute a command:

Start consultation

Consultation

Always lead with a strong verb that encourages action. To provide enough context to user, use the {verb} + {noun} content formula:

Open dashboard

Dashboard

When writing command titles, always write them in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):

New appointment

New Appointment

Avoid unnecessary words and articles in command titles, such as “the”, “an” or “a”:

Change theme

Change the theme

Avoid ending in punctuation:

Switch user

Switch user.

Use ellipsis in the title when describing sections that have commands grouped inside of them:

Change theme…

Change theme

Commands data #

Each command in the commands data array must include at least an id and title. A command may also include properties for section, icon, handler, shortcut , parent, and keywords:

Name	Purpose
`id`	An identifier for each command, must be unique. Example: `id: "user"`.
`title`	The title shown to users. This is used when searching for a command. Example: `title: "Change theme..."`.
`keywords`	Not visible in the user interface, but can make it easier to discover commands through search. Example: `keywords: "command change log sign out in"`.
`shortcut`	The keyboard shortcut. Example: `shortcut: "Alt+KeyU"`. See the sections Defining Shortcuts and Choosing shortcuts below for more information.
`section`	Used for grouping many commands under a common header. Example: `section: "Commands"`.
`icon`	A name of an icon form Nordicons to show beside the title. If not specified, default command icon will be used instead. Example: `icon: "file-picture"`.
`parent`	The `id` of a parent command. This is used for nesting commands. Example: `parent: "theme"`.
`handler`	A function to execute when an user triggers a command. Example: `handler: () => { alert("Change to light theme") }`. In cases where a command is only used as a parent command e.g. "Change theme", this is not required.

Defining shortcuts #

Shortcuts in the Command Menu have the following form: [modifier]+[key]. Shortcuts are made up of a sequence of presses. A press can be as simple as a single key which matches against KeyboardEvent.code:

// Matches: event.code:
"KeyD"

Presses can optionally be prefixed with modifiers which match against any valid value to KeyboardEvent.getModifierState().

"Control+KeyD"
"Meta+KeyD"
"Shift+KeyD"
"Alt+KeyD"
"Meta+Shift+KeyD"

There is also a special $mod modifier that makes it easy to support cross platform keybindings:

Mac: $mod = Meta (⌘)
Windows/Linux: $mod = Control

"$mod+KeyD" // ⌘/Ctrl + D
"$mod+Shift+KeyD" // ⌘/Ctrl + Shift + D

The Command Menu itself can be opened using ⌘+k (or Ctrl+k on Windows) and closed by hitting Esc. These are both non-configurable shortcuts in order to unify the experience across our platforms.

Choosing shortcuts #

When choosing shortcuts, it is very important that they do not clash with native operating system or browser shortcuts.

For example, you should not define a shortcut like $mod+KeyC, since this will clash with the native “Copy” shortcut, and will be triggered every time a user copies text in the app. Nor should you use shortcuts like Shift+KeyA since this will get triggered whenever a user types an uppercase “A” character. Therefore, special care and attention must be given to each and every shortcut choice.

In general, we recommend using the Alt modifier, since this is less likely to clash with existing shortcuts. However, be aware, the Alt key is also used for accented characters e.g. Alt+KeyA produces the letter “å”. Again, it is crucial that you choose shortcuts carefully.

You should strive to choose shortcuts that are intuitive and easy to remember. The more complex a shortcut, the less likely a user is to remember it. Of course, a user can still find a command by searching the command menu, and for some users this may be their preferred way of triggering commands.

Common keybindings #

Keybindings will be matched against KeyboardEvent.key and KeyboardEvent.code which may have some names you don’t expect. Please note that we recommend always using KeyboardEvent.code for defining the keys and only using KeyboardEvent.key for defining modifiers.

Windows	macOS	key	code
N/A	`Command` / `⌘`	`Meta`	`MetaLeft` / `MetaRight`
`Alt`	`Option` / `⌥`	`Alt`	`AltLeft` / `AltRight`
`Control`	`Control` / `^`	`Control`	`ControlLeft` / `ControlRight`
`Shift`	`Shift`	`Shift`	`ShiftLeft` / `ShiftRight`
`Space`	`Space`	N/A	`Space`
`Enter`	`Return`	`Enter`	`Enter`
`Esc`	`Esc`	`Escape`	`Escape`
`1`, `2`, etc	`1`, `2`, etc	`1`, `2`, etc	`Digit1`, `Digit2`, etc
`a`, `b`, etc	`a`, `b`, etc	`a`, `b`, etc	`KeyA`, `KeyB`, etc
`-`	`-`	`-`	`Minus`
`=`	`=`	`=`	`Equal`
`+`	`+`	`+`	`Equal`*

In addition to the above table, you can use https://keycode.info/ for checking the specific values needed. Note that some keys will have the same code as others because they appear on the same key on the keyboard. Keep in mind how this is affected by international keyboards which may have different layouts.

Use Ctrl+K (Windows/Linux) or Cmd+K (Mac) to open the command menu.
Start typing the command you want to execute. The suggestions in the command menu change to match your text.
Finish entering the name, or use the arrow keys to highlight the command you want from the list of suggestions.
Use Enter to execute the chosen command.
If you chose a command that has nested commands, you can use Backspace to return to the previous menu.
When the command menu is active, you can use one of the following keyboard shortcuts to close it: Esc, Ctrl+K (Windows and Linux) or Cmd+K (Mac).

Integration

For integration guidelines, please see Web Components documentation. This documentation explains how to implement and use Nord Web Components across different technologies such as Vue.js, React, or Vanilla JavaScript.

Integration Guidelines

Troubleshooting

If you experience any issues while using Nord Web Components, please head over to the Support page for more guidelines and ways to contact us.