Menu Bar Commands

The MenuBarExtra component can be used to create commands which populate the extras section of macOS' menu bar.

Getting Started

If you don't have an extension yet, follow the guide and then return to this page. Now that your extension is ready, let's open its package.json file and add a new entry to its commands array, ensuring its mode property is set to menu-bar. For this guide, let's add the following:

Create github-pull-requests.tsx in your extensions src/ folder and add the following:

If your development server is running, the command should appear in your root search, and running the command should result in the GitHub icon appearing in your menu bar.

Of course, our pull request command wouldn't be of that much use if we had to tell it to update itself every single time. To add to our command, we need to open the package.json file we modified earlier and add an interval key to the command configuration object:

Your root search should look similar to:

Running it once should activate it to:

Lifecycle

Although menu-bar commands can result in items permanently showing up in the macOS menu bar, they are not long-lived processes. Instead, as with other commands, Raycast loads them into memory on demand, executes their code and then tries to unload them at the next convenient time. There are five distinct events that can result in a menu-bar's item being placed in the menu bar, so let's walk through each one.

From the root search

Same as any other commands, menu-bar commands can be run directly from Raycast's root search. Eventually, they may result in a new item showing up in your menu bar (if you have enough room and if the command returns a MenuBarExtra), or in a previous item disappearing, if the command returns null. In this case, Raycast will load your command code, execute it, wait for the MenuBarExtra's isLoading prop to switch to false, and unload the command.

At a set interval

If your menu-bar command also makes use of and it has background refresh activated, Raycast will run the command at set intervals. In your command, you can use environment.launchType to check whether it is launched in the background or by the user.

When the user clicks the command's icon / title in the menu bar

One of the bigger differences to view or no-view commands is that menu-bar commands have an additional entry point: when the user clicks their item in the menu bar. If the item has a menu (i.e. MenuBarExtra provides at least one child), Raycast will load the command code, execute it and keep it in memory while the menu is open. When the menu closes (either by the user clicking outside, or by clicking a MenuBarExtra.Item), the command is then unloaded.

When Raycast is restarted

This case assumes that your command has run at least once, resulting in an item being placed in the menu bar. If that's the case, quitting and starting Raycast again should put the same item in your menu bar. However, that item will be restored from Raycast's database - not by loading and executing the command.

When a menu bar command is re-enabled in preferences

This case should work the same as when Raycast is restarted.

Best practices

• make generous use of the and our in order to provide quick feedback and ensure action handlers work as expected

• make sure you set isLoading to false when your command finishes executing

• avoid setting long titles in MenuBarExtra, MenuBarExtra.Submenu or

API Reference

MenuBarExtra

Adds an item to the menu bar, optionally with a menu attached in case its children prop is non-empty.

Example

Props

MenuBarExtra.Item

An item in the or in a .

Example

Props

MenuBarExtra.Submenu

MenuBarExtra.Submenus reveal their items when people interact with them. They're a good way to group items that naturally belong together, but keep in mind that submenus add complexity to your interface - so use them sparingly!

Example

Props

MenuBarExtra.Section

An item to group related menu items. It has an optional title and a separator is added automatically between sections.

Example

Props

Types

MenuBarExtra.ActionEvent

An interface describing Action events in callbacks.

Properties

Example