prosemirror-semantic-menu

A menu plugin for ProseMirror that uses semantic HTML.

Table of Contents

• prosemirror-semantic-menu
  • Table of Contents
  • Installation
  • Usage
    • Styling
  • Documentation
    • Hand-rolled Types
    • Exports
      • MenuView
      • menuPlugin()
      • menuPluginKey
      • MenuItemButton
      • MenuItemSelect
      • ProseMirrorMenu
      • styles/menu.css

Installation

npm i prosemirror-semantic-menu

Usage

Import the menuPlugin() function with all of your other ProseMirror code:

import { EditorState } from "prosemirror-state";
import { EditorView } from "prosemirror-view";
import { menuPlugin } from "prosemirror-semantic-menu";

const schema = new Schema(
  // SchemaSpec goes here
);

new EditorView(document.querySelector("#editor"), {
  state: EditorState.create({
    schema: schema,
    plugins: [
      // load other plugins
      menuPlugin({
        items: [
          // place your menu items here
        ]
      }),
    ],
  }),
});

Styling

An example stylesheet is also provided. You can import it for bundler use from prosemirror-semantic-menu/styles/menu.css.

The component's shadow root is set to open, meaning you can append content to it after it is attached to the editor. This is useful for things like improving the editor's initial render time while deferring icon loading via an HTTP request.

Documentation

This module exports a function, view, and plugin key for creating a menu, as well as classes for creating different types of items.

A few interfaces are defined for type checking, and type declarations for the exported items are generated from JSDoc annotations in the code.

A quick reference is below; refer to the documentation comments in the code and its corresponding type declarations for a more thorough breakdown.

Hand-rolled Types

• interface MenuElement: All menu items conform to this interface
• interface MenuElementOptions: The object passed to the constructor of a menu item
• interface SelectChoice: An object representing a single <option> element in a <select> control

Exports

MenuView

The class for creating and updating the menu's markup.

menuPlugin()

A function that returns a plugin you can pass to the editor state. It takes an object with the following options as an argument:

• items: An array of objects that represent the menu items
• element: The Element into which the menu should be adjacently inserted
• where: The InsertPosition indicating where to insert the menu relative to the element key

menuPluginKey

The key of the plugin created by menuPlugin().

MenuItemButton

Create a <button> element that executes a function when pressed.

MenuItemSelect

Create a <select> element that executes a function when its value changes. The function is meant to be the same no matter what value is chosen, with the selection acting as an argument to the function.

ProseMirrorMenu

The class for the custom element that contains the menu. The custom element uses shadow DOM, and it exposes elements for styling via the part attribute.

styles/menu.css

An example of how one could style the menu's shadow DOM via the ::part() pseudo-element. It provides hover, focus, and active styles.