# menu

> The menu plugin: an Edit switch and a small menu in the top right for people who can edit, with an API to add your own items.

Source: https://clayjs.com/docs/plugins/menu/

The menu plugin gives someone who can edit a way back into editing without the keyboard. Ask for it by name: `?plugins=menu`.

## What it draws

A small group in the top right, shown only to someone who can edit: an Edit switch that changes mode in one click through [`clay.setMode`](https://clayjs.com/docs/api/), and claygoo beside it opening a menu. Everything it draws is `clay="editor-ui"`, so nothing from it reaches the saved file, a sync frame, the dirty check or undo.

It loads in view mode too: without it a document builds its own toggle. A visitor's draft gets neither, since a draft has nothing to switch.

## SEO settings

**SEO settings…** in claygoo's menu opens a panel that slides down from the top of the page. It lets you control how the document appears in search results and shared link previews without editing `<head>` tags by hand.

The sheet displays a preview card showing the shared link's image, title, description, and host (taken from the canonical URL, or the current host when none is set), alongside four groups of fields:

- Basics: **Title**, **Description**, **Language**, and **Canonical URL** (a localhost address is refused with "A localhost address cannot be a canonical URL.").
- Search: **Show in search results** and **Let search engines follow links** checkboxes.
- Link preview: **Preview title**, **Preview description**, **Preview image**, **Image alt text**, and **Site name**. Where the host supports uploads, **Preview image** has an upload button and notes "Uploaded images are public to anyone with the link."; otherwise it asks you to "Paste the address of an image on the web."
- Social card: **Handle**.

On a [page](https://clayjs.com/docs/plugins/page/) document (`article[data-page]`), **Title** follows the document's first heading. Typing a title in the sheet switches it to custom mode and writes `<meta name="clay-seo-title-mode" content="custom">` to the head. A **Use the first heading** button then appears under **Title** to hand the title back to the first heading.

The sheet is marked `clay="editor-ui"`, and opening or cancelling it changes nothing in the document. Clicking **Apply** writes the head fields in one step through `clay.undo.commit` when the [undo](https://clayjs.com/docs/plugins/undo/) plugin is loaded.

## Add your own items

`clay.menu.addItem({ id, label, run, badge })` appends a menu item. A duplicate id replaces the earlier item, and `badge` puts a dot on claygoo. `clay.menu.open()` and `clay.menu.close()` drive the list from your own code.

## Across a mode change

The menu has no lease of its own. It reads the mode at the moment something happens, on a document that [switches without a reload](https://clayjs.com/docs/guide/edit-mode/#switching-without-a-reload-clay-mode-switch-live) as well as on one that reloads.

The Edit switch follows the committed mode, not the click. Every commit fires `clay:modechange` and the switch reads its state then, so a change that came from the keyboard, from another plugin's lease, or from a page this menu did not start still lands on it. The switch is busy until the answer arrives, and a refused change puts it back and says why ([Leaving edit](https://clayjs.com/docs/guide/edit-mode/#leaving-edit)).

The menu mounts when `canEdit` turns true, which the page announces as `clay:capabilitychange`. A document that gains the capability after boot gets the menu without a reload.

The SEO settings sheet is read-only in view: its fields are disabled, and it offers an Edit button in place of Apply. That button asks for edit mode and writes the `reopen-seo` receipt only for the reload path; a live entry keeps the page and the sheet where they are, drops the receipt and re-lays the sheet out from `clay:modechange`.
