@extend-chrome/menus

A powerful context menu API to take your Chrome extension to the next level.

This library is in alpha until further notice. Things may not work. The API may change between minor versions.

Getting Started
Usage
Features
API

Getting started

You will need to use a bundler like Rollup, Parcel, or Webpack to include this library in the build of Chrome extension.

See rollup-plugin-chrome-extension for an easy way use Rollup to build your Chrome extension!

Installation

$ npm i @extend-chrome/menus

Usage

// background.js
import { menus } from '@extend-chrome/menus'

const id = 'my-menu'

// Create a menu
menus.create({ id, title: 'My Menu' })

// Use the included Observable of menu item clicks
menus.clickStream.subscribe(([clickData, tab]) => {
  console.log('They clicked', clickData.id)
  console.log('In tab', tab.id)

  menus.update({ id, title: 'Another Title' })
})

Features

Dynamic Context Menus

A dynamic context menu is only available on HTML elements that match the CSS selector defined in its options.

import { menus } from '@extend-chrome/menus'

menus.create({
  id: 'my-dynamic-menu',
  title: 'I only show on H1 tags',
  selector: 'h1',
})

This feature uses chrome.tabs.executeScript under the hood, so it only works on pages found in the manifest permissions field.

// manifest.json
{
  ...
  permissions: ['https://www.youtube.com/*']
  ...
}

RxJs Observables

Chrome extensions and RxJs are a match made in heaven. Take advantage of ready-made Observables of menu item clicks, creations, updates, and removals.

import { menus } from '@extend-chrome/menus'

menus.clickStream.subscribe(([clickData, tab]) => {
  console.log('Menu Item Id', clickData.id)
  console.log('Tab Id', tab.id)
})

Convenience Function `useMenu`

The function useMenu creates a menu item and returns a tuple array of an updater function and an Observable of clicks for that menu item.

import { useMenu } from '@extend-chrome/menus'

const menuOptions = {
  id: 'menu1',
  title: 'Menu Item One',
  type: 'checkbox',
  checked: false,
}

const [
  // Updates only this menu item
  updateMenu,
  // Emits only clicks for this menu item
  menuClickStream,
] = useMenu(menuOptions)

menuClickStream.subscribe(([clickData, tab]) => {
  // No need to include menu id
  // Toggle menu item checkbox
  updateMenu({ checked: !clickData.checked })
})

Full TypeScript Support

@extend-chrome/menus is written in TypeScript and includes type definitions. Functions and Observables are fully typed, so Intellisense works well.

import { useMenu, ContextMenuOptions } from '@extend-chrome/menus'

const menuOptions: ContextMenuOptions = {
  id: 'menu1',
  title: 'Menu Item One',
}

const [updateMenu, menuClickStream]: [
  (options: Partial<ContextMenuOptions>) => void
  Observable<[ContextMenuClickData, chrome.tabs.Tab]>
] = useMenu(menuOptions)

Options API

Full documentation coming soon!

There's great TypeScript support however, so Intellisense is your friend in the meantime.

@extend-chrome/menus