Menus

Version:

Example🔗

The following is an example of the format of a .sublime-menu file.

[
    {
        "caption": "File",
        "mnemonic": "F",
        "id": "file",
        "children":
        [
            { "command": "new_file", "caption": "New File", "mnemonic": "N" },

            { "command": "prompt_open_file", "caption": "Open File…", "mnemonic": "O", "platform": "!OSX" },
            { "command": "prompt_open_folder", "caption": "Open Folder…", "platform": "!OSX" },
            { "command": "prompt_open", "caption": "Open…", "platform": "OSX" }
        ]
    }
]

Entries🔗

Each menu entry is a JSON object with one or more keys. The list of supported keys includes:

"caption"🔗

The text of the menu entry.

"mnemonic"🔗

The character to use as the key to press to activate the entry. Only applies to Windows and Linux. Must match the case of the character in the "caption".

"command"🔗

A string of the command to execute when the entry is activated.

"args"🔗

A JSON object of args to send to the command.

"children"🔗

A JSON array of entries to create a submenu from.

"id"🔗

A unique string for the menu entry. Used for menu entries with "children" to allow adding additional child entries.

"platform"🔗

One of the strings: "OSX", "!OSX", "Windows", "!Windows", "Linux" or "!Linux". Controls what platforms the entry is shown on.

Each menu entry requires at minimum, the key "caption" for a non-functionality entry, or "command" for an entry that performs an action.

Available Menus🔗

Sublime Text has seven menus that may be customized:

Main.sublime-menu

Primary menu for the application.

Side Bar Mount Point.sublime-menu

Context menu for top-level folders in the side bar.

Side Bar.sublime-menu

Context menu for files and folders in the side bar. Has “magic” args for passing file and folder names to commands.

Entries with an arg "files": [] will be enabled for files and will pass file names to the command via the arg files. Entries with an arg "dirs": [] will be enabled for folders and will pass file names to the command via the arg dirs. Entries with an arg "paths": [] will be enabled for files and folders and will pass file and folder names to the command via the arg paths.

Tab Context.sublime-menu

Context menu for file tabs

Context.sublime-menu

Context menu for text areas

Find in Files.sublime-menu

Menu shown when clicking the ... button in Find in Files panel

Widget Context.sublime-menu

Context menu for text inputs in various panels. Technically this file name can be changed via the context_menu setting inside of Widget.sublime-settings.*

Adding to Submenus🔗

Using the "id" key of an entry, it is possible to add entries to submenus. When adding submenu entries, specify only the "id" and "children" keys of the parent entry, and set the value of "children" to an array of entries to append to the submenu.

For example, to add a new layout to the View Layout menu, create an entry such as:

[
    {
        "id": "layout",
        "children":
        [
            {
                "caption": "Grid: 9",
                "command": "set_layout",
                "args":
                {
                    "cols": [0.0, 0.33, 0.66, 1.0],
                    "rows": [0.0, 0.33, 0.66, 1.0],
                    "cells":
                    [
                        [0, 0, 1, 1], [1, 0, 2, 1], [2, 0, 3, 1],
                        [0, 1, 1, 2], [1, 1, 2, 2], [2, 1, 3, 2],
                        [0, 2, 1, 3], [1, 2, 2, 3], [2, 2, 3, 3]
                    ]
                }
            },
        ]
    }
]

To find the "id" of entries in the Main.sublime-menu, use the View Package File command from the command palette and select Default/Main.sublime-menu.

Customization🔗

Users can customize the available menus by creating an appropriately-named file in their Packages/User/ directory.

For example, to customize the context menu for files and folders in the side bar, create a file named Packages/User/Side Bar.sublime-menu. Adding the following would create an entry that would execute a (hypothetical) command that would copy the path to the clipboard.

[
    {
        "caption": "Copy Full Path",
        "mnemonic": "y",
        "command": "copy_path",
        "args": {"paths": []}
    }
]