• Stars
    star
    1,297
  • Rank 36,273 (Top 0.8 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 8 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Context menu for your Electron app

electron-context-menu

Context menu for your Electron app

Electron doesn't have a built-in context menu. You're supposed to handle that yourself. But it's both tedious and hard to get right. This module gives you a nice extensible context menu with spellchecking and items like Cut/Copy/Paste for text, Save Image for images, and Copy Link for links. It also adds an Inspect Element menu item when in development to quickly view items in the inspector like in Chrome.

This package can only be used in the main process.

Install

$ npm install electron-context-menu

Requires Electron 10 or later.

Usage

const {app, BrowserWindow} = require('electron');
const contextMenu = require('electron-context-menu');

contextMenu({
	showSaveImageAs: true
});

let mainWindow;
(async () => {
	await app.whenReady();

	mainWindow = new BrowserWindow({
		webPreferences: {
			spellcheck: true
		}
	});
})();

Advanced example:

const {app, BrowserWindow, shell} = require('electron');
const contextMenu = require('electron-context-menu');

contextMenu({
	prepend: (defaultActions, parameters, browserWindow) => [
		{
			label: 'Rainbow',
			// Only show it when right-clicking images
			visible: parameters.mediaType === 'image'
		},
		{
			label: 'Search Google for โ€œ{selection}โ€',
			// Only show it when right-clicking text
			visible: parameters.selectionText.trim().length > 0,
			click: () => {
				shell.openExternal(`https://google.com/search?q=${encodeURIComponent(parameters.selectionText)}`);
			}
		}
	]
});

let mainWindow;
(async () => {
	await app.whenReady();

	mainWindow = new BrowserWindow({
		webPreferences: {
			spellcheck: true
		}
	});
})();

The return value of contextMenu() is a function that disposes of the created event listeners:

const dispose = contextMenu();

dispose();

API

contextMenu(options?)

Creates a context menu and returns a dispose function.

options

Type: object

window

Type: BrowserWindow | BrowserView | WebViewTag | WebContents

Window or WebView to add the context menu to.

When not specified, the context menu will be added to all existing and new windows.

prepend

Type: Function

Should return an array of MenuItem's to be prepended to the context menu.

The first argument is an array of default actions that can be used. The second argument is this parameters object. The third argument is the BrowserWindow the context menu was requested for. The fourth argument is the context menu event.

MenuItem labels may contain the placeholder {selection} which will be replaced by the currently selected text as described in options.labels.

append

Type: Function

Should return an array of MenuItem's to be appended to the context menu.

The first argument is an array of default actions that can be used. The second argument is this parameters object. The third argument is the BrowserWindow the context menu was requested for. The fourth argument is the context menu event.

MenuItem labels may contain the placeholder {selection} which will be replaced by the currently selected text as described in options.labels.

showLearnSpelling

Type: boolean
Default: true

Show the Learn Spelling {selection} menu item when right-clicking text.

Even if true, the spellcheck preference in browser window must still be enabled. It will also only show when right-clicking misspelled words.

showLookUpSelection

Type: boolean
Default: true

Show the Look Up {selection} menu item when right-clicking text.

showSearchWithGoogle

Type: boolean
Default: true

Show the Search with Google menu item when right-clicking text.

showSelectAll

Type: boolean
Default: false on macOS, true on Windows and Linux

Show the Select All menu item when right-clicking in a window.

showCopyImage

Type: boolean
Default: true

Show the Copy Image menu item when right-clicking on an image.

showCopyImageAddress

Type: boolean
Default: false

Show the Copy Image Address menu item when right-clicking on an image.

showSaveImage

Type: boolean
Default: false

Show the Save Image menu item when right-clicking on an image.

showSaveImageAs

Type: boolean
Default: false

Show the Save Image Asโ€ฆ menu item when right-clicking on an image.

showCopyVideoAddress

Type: boolean
Default: false

Show the Copy Video Address menu item when right-clicking on a video.

showSaveVideo

Type: boolean
Default: false

Show the Save Video menu item when right-clicking on a video.

showSaveVideoAs

Type: boolean
Default: false

Show the Save Video Asโ€ฆ menu item when right-clicking on a video.

showCopyLink

Type: boolean
Default: true

Show the Copy Link menu item when right-clicking on a link.

showSaveLinkAs

Type: boolean
Default: false

Show the Save Link Asโ€ฆ menu item when right-clicking on a link.

showInspectElement

Type: boolean
Default: Only in development

Force enable or disable the Inspect Element menu item.

showServices

Type: boolean
Default: false

Show the system Services submenu when right-clicking text on macOS.

Note: Due to a bug in the Electron implementation, this menu is not identical to the "Services" submenu in the context menus of native apps. Instead, it looks the same as the "Services" menu in the main App Menu. For this reason, it is currently disabled by default.

labels

Type: object
Default: {}

Override labels for the default menu items. Useful for i18n.

The placeholder {selection} may be used in any label, and will be replaced by the currently selected text, trimmed to a maximum of 25 characters length. This is useful when localizing the Look Up โ€œ{selection}โ€ menu item, but can also be used in custom menu items, for example, to implement a Search Google for โ€œ{selection}โ€ menu item. If there is no selection, the {selection} placeholder will be replaced by an empty string. Normally this placeholder is only useful for menu items which will only be shown when there is text selected. This can be checked using visible: parameters.selectionText.trim().length > 0 when implementing a custom menu item, as shown in the usage example above.

Format:

{
	labels: {
		copy: 'Copiar',
		saveImageAs: 'Guardar imagen comoโ€ฆ',
		lookUpSelection: 'Consultar โ€œ{selection}โ€'
	}
}

shouldShowMenu

Type: Function

Determines whether or not to show the menu. Can be useful if you for example have other code presenting a context menu in some contexts.

The second argument is this parameters object.

Example:

{
	// Doesn't show the menu if the element is editable
	shouldShowMenu: (event, parameters) => !parameters.isEditable
}

menu

Type: Function

This option lets you manually pick what menu items to include. It's meant for advanced needs. The default menu with the other options should be enough for most use-cases, and it ensures correct behavior, for example, correct order of menu items. So prefer the append and prepend option instead of menu whenever possible.

The function passed to this option is expected to return MenuItem[]. The first argument the function receives is an array of default actions that can be used. These actions are functions that can take an object with a transform property (except for separator and inspect). The transform function will be passed the content of the action and can modify it if needed. If you use transform on cut, copy, or paste, they will convert rich text to plain text. The second argument is this parameters object. The third argument is the BrowserWindow the context menu was requested for. The fourth argument is an Array of menu items for dictionary suggestions. This should be used if you wish to implement spellcheck in your custom menu. The last argument is the context menu event.

Even though you include an action, it will still only be shown/enabled when appropriate. For example, the saveImage action is only shown when right-clicking an image.

MenuItem labels may contain the placeholder {selection} which will be replaced by the currently selected text as described in options.labels.

To get spellchecking, โ€œCorrect Automaticallyโ€, and โ€œLearn Spellingโ€ in the menu, please enable the spellcheck preference in browser window: new BrowserWindow({webPreferences: {spellcheck: true}})

The following options are ignored when menu is used:

  • showLookUpSelection
  • showSearchWithGoogle
  • showSelectAll
  • showCopyImage
  • showCopyImageAddress
  • showSaveImageAs
  • showCopyVideoAddress
  • showSaveVideo
  • showSaveVideoAs
  • showCopyLink
  • showSaveLinkAs
  • showInspectElement
  • showServices

Default actions:

  • spellCheck
  • learnSpelling
  • separator
  • lookUpSelection
  • searchWithGoogle
  • cut
  • copy
  • paste
  • selectAll
  • saveImage
  • saveImageAs
  • saveVideo
  • saveVideoAs
  • copyImage
  • copyImageAddress
  • copyVideoAddress
  • copyLink
  • saveLinkAs
  • inspect
  • services

Example for actions:

{
	menu: (actions, props, browserWindow, dictionarySuggestions) => [
		...dictionarySuggestions,
		actions.separator(),
		actions.copyLink({
			transform: content => `modified_link_${content}`
		}),
		actions.separator(),
		{
			label: 'Unicorn'
		},
		actions.separator(),
		actions.copy({
			transform: content => `modified_copy_${content}`
		}),
		{
			label: 'Invisible',
			visible: false
		},
		actions.paste({
			transform: content => `modified_paste_${content}`
		})
	]
}

onShow

Type: Function

Called when the context menu is shown.

The function receives an Event object.

onClose

Type: Function

Called when the context menu is closed.

The function receives an Event object.

Related

More Repositories

1

awesome

๐Ÿ˜Ž Awesome lists about all kinds of interesting topics
270,042
star
2

awesome-nodejs

โšก Delightful Node.js packages and resources
52,854
star
3

awesome-electron

Useful resources for creating apps with Electron
25,634
star
4

quick-look-plugins

List of useful Quick Look plugins for developers
17,497
star
5

got

๐ŸŒ Human-friendly and powerful HTTP request library for Node.js
TypeScript
14,218
star
6

type-fest

A collection of essential TypeScript types
TypeScript
14,015
star
7

ky

๐ŸŒณ Tiny & elegant JavaScript HTTP client based on the Fetch API
TypeScript
13,762
star
8

pure

Pretty, minimal and fast ZSH prompt
Shell
12,391
star
9

pageres

Capture website screenshots
TypeScript
9,573
star
10

ora

Elegant terminal spinner
JavaScript
8,591
star
11

np

A better `npm publish`
JavaScript
7,529
star
12

github-markdown-css

The minimal amount of CSS to replicate the GitHub Markdown style
CSS
7,421
star
13

caprine

Elegant Facebook Messenger desktop app
TypeScript
7,014
star
14

screenfull

Simple wrapper for cross-browser usage of the JavaScript Fullscreen API
HTML
6,891
star
15

Gifski

๐ŸŒˆ Convert videos to high-quality GIFs on your Mac
Swift
6,807
star
16

fkill-cli

Fabulously kill processes. Cross-platform.
JavaScript
6,782
star
17

query-string

Parse and stringify URL query strings
JavaScript
6,453
star
18

execa

Process execution for humans
JavaScript
6,019
star
19

modern-normalize

๐Ÿ’ Normalize browsers' default style
TypeScript
5,038
star
20

css-in-readme-like-wat

Style your readme using CSS with this simple trick
5,013
star
21

awesome-npm

Awesome npm resources and tips
4,315
star
22

promise-fun

Promise packages, patterns, chat, and tutorials
4,277
star
23

awesome-scifi

Sci-Fi worth consuming
4,268
star
24

electron-store

Simple data persistence for your Electron app or module - Save and load user preferences, app state, cache, etc
JavaScript
4,165
star
25

create-dmg

Create a good-looking DMG for your macOS app in seconds
JavaScript
3,950
star
26

speed-test

Test your internet connection speed and ping using speedtest.net from the CLI
JavaScript
3,882
star
27

eslint-plugin-unicorn

More than 100 powerful ESLint rules
JavaScript
3,877
star
28

ow

Function argument validation for humans
TypeScript
3,799
star
29

file-type

Detect the file type of a file, stream, or data
JavaScript
3,632
star
30

meow

๐Ÿˆ CLI app helper
JavaScript
3,305
star
31

p-queue

Promise queue with concurrency control
TypeScript
3,202
star
32

open

Open stuff like URLs, files, executables. Cross-platform.
JavaScript
2,976
star
33

Plash

๐Ÿ’ฆ Make any website your Mac desktop wallpaper
Swift
2,735
star
34

alfy

Create Alfred workflows with ease
JavaScript
2,570
star
35

trash

Move files and directories to the trash
JavaScript
2,512
star
36

fast-cli

Test your download and upload speed using fast.com
JavaScript
2,484
star
37

guides

A collection of succinct guides - Public Domain
2,424
star
38

globby

User-friendly glob matching
JavaScript
2,376
star
39

slugify

Slugify a string
JavaScript
2,357
star
40

emoj

Find relevant emoji from text on the command-line ๐Ÿ˜ฎ โœจ ๐Ÿ™Œ ๐Ÿด ๐Ÿ’ฅ ๐Ÿ™ˆ
JavaScript
2,311
star
41

cli-spinners

Spinners for use in the terminal
JavaScript
2,255
star
42

on-change

Watch an object or array for changes
JavaScript
1,966
star
43

devtools-detect

Detect if DevTools is open and its orientation
HTML
1,924
star
44

gulp-imagemin

Minify PNG, JPEG, GIF and SVG images
JavaScript
1,903
star
45

touch-bar-simulator

Use the Touch Bar on any Mac
Swift
1,900
star
46

notifier-for-github

Browser extension - Get notified about new GitHub notifications
JavaScript
1,828
star
47

editorconfig-sublime

Sublime Text plugin for EditorConfig - Helps developers maintain consistent coding styles between different editors
Python
1,757
star
48

emittery

Simple and modern async event emitter
JavaScript
1,721
star
49

is

Type check values
TypeScript
1,678
star
50

capture-website

Capture screenshots of websites
JavaScript
1,670
star
51

Defaults

๐Ÿ’พ Swifty and modern UserDefaults
Swift
1,661
star
52

electron-boilerplate

Boilerplate to kickstart creating an app with Electron
JavaScript
1,632
star
53

pageres-cli

Capture website screenshots
JavaScript
1,620
star
54

clipboardy

Access the system clipboard (copy/paste)
JavaScript
1,598
star
55

gulp-rev

Static asset revisioning by appending content hash to filenames: `unicorn.css` โ†’ `unicorn-d41d8cd98f.css`
JavaScript
1,538
star
56

pify

Promisify a callback-style function
JavaScript
1,494
star
57

boxen

Create boxes in the terminal
JavaScript
1,467
star
58

Actions

โš™๏ธ Supercharge your shortcuts
Swift
1,437
star
59

multiline

Multiline strings in JavaScript
JavaScript
1,424
star
60

hyper-snazzy

Elegant Hyper theme with bright colors
JavaScript
1,412
star
61

amas

Awesome & Marvelous Amas
1,392
star
62

LaunchAtLogin

Add โ€œLaunch at Loginโ€ functionality to your macOS app in seconds
Swift
1,346
star
63

del

Delete files and directories
JavaScript
1,316
star
64

refined-twitter

Browser extension that simplifies the Twitter interface and adds useful features
JavaScript
1,313
star
65

KeyboardShortcuts

โŒจ๏ธ Add user-customizable global keyboard shortcuts (hotkeys) to your macOS app in minutes
Swift
1,313
star
66

iterm2-snazzy

Elegant iTerm2 theme with bright colors
1,313
star
67

p-limit

Run multiple promise-returning & async functions with limited concurrency
JavaScript
1,294
star
68

Settings

โš™ Add a settings window to your macOS app in minutes
Swift
1,282
star
69

trash-cli

Move files and folders to the trash
JavaScript
1,244
star
70

electron-util

Useful utilities for Electron apps and modules
JavaScript
1,188
star
71

is-online

Check if the internet connection is up
JavaScript
1,181
star
72

ponyfill

๐Ÿฆ„ Like polyfill but with pony pureness
1,136
star
73

conf

Simple config handling for your app or module
TypeScript
1,109
star
74

anatine

[DEPRECATED] ๐Ÿฆ Pristine Twitter app
JavaScript
1,097
star
75

electron-dl

Simplified file downloads for your Electron app
JavaScript
1,087
star
76

log-update

Log by overwriting the previous output in the terminal. Useful for rendering progress bars, animations, etc.
JavaScript
1,027
star
77

pretty-bytes

Convert bytes to a human readable string: 1337 โ†’ 1.34 kB
JavaScript
1,022
star
78

grunt-sass

Compile Sass to CSS
JavaScript
1,020
star
79

mem

Memoize functions - an optimization technique used to speed up consecutive function calls by caching the result of calls with identical input
TypeScript
1,019
star
80

DockProgress

Show progress in your app's Dock icon
Swift
1,003
star
81

wallpaper

Manage the desktop wallpaper
JavaScript
996
star
82

p-map

Map over promises concurrently
JavaScript
996
star
83

public-ip

Get your public IP address - very fast!
JavaScript
979
star
84

gulp-app

[DEPRECATED] Gulp as an app
JavaScript
961
star
85

grunt-shell

Run shell commands
JavaScript
952
star
86

load-grunt-tasks

Load multiple grunt tasks using globbing patterns
JavaScript
940
star
87

hasha

Hashing made simple. Get the hash of a buffer/string/stream/file.
JavaScript
934
star
88

pretty-ms

Convert milliseconds to a human readable string: `1337000000` โ†’ `15d 11h 23m 20s`
JavaScript
929
star
89

terminal-image

Display images in the terminal
JavaScript
923
star
90

object-assign

ES2015 Object.assign() ponyfill
JavaScript
922
star
91

copy-text-to-clipboard

Copy text to the clipboard in modern browsers (0.2 kB)
JavaScript
858
star
92

System-Color-Picker

๐ŸŽจ The macOS color picker as an app with more features
Swift
842
star
93

normalize-url

Normalize a URL
JavaScript
818
star
94

get-port

Get an available TCP port
JavaScript
817
star
95

atom-editorconfig

Helps developers maintain consistent coding styles between different editors
JavaScript
811
star
96

grunt-concurrent

Run grunt tasks concurrently
JavaScript
799
star
97

dot-prop

Get, set, or delete a property from a nested object using a dot path
JavaScript
777
star
98

p-progress

Create a promise that reports progress
TypeScript
751
star
99

gulp-changed

Only pass through changed files
JavaScript
747
star
100

generator-nm

Scaffold out a node module
JavaScript
742
star