UI surfaces

Plugin actions can appear in several places. Choose the smallest surface that matches the workflow. For continuously visible info instead of click-driven actions, see Status bars.

Menus and toolbar

Surface	Fields	Context
Selection context menu	menu = "context", where = { "selection" }	Acts on ctx.paths.
Background context menu	menu = "context", where = { "background" }	Acts on ctx.dir; ctx.paths is empty.
Top Plugins menu	menu = "menubar"	Good for global commands.
Location toolbar	menu = "toolbar"	Always visible; acts on ctx.dir.

For context menus, where defaults to { "selection" }.

Grouped context menu

Actions with the same group are nested under one submenu.

local GROUP = "Compress with 7-Zip"

waydir.register({
  id = "zip",
  group = GROUP,
  title = "Compress to .zip",
  icon = "file-zip",
  when = { min = 1, in_archive = false },
  run = function(ctx)
    -- ...
  end,
})

Settings

Declare settings on any contribution. Waydir combines each plugin's settings schema, deduplicates fields by id, stores values as JSON, and injects defaults plus saved values into ctx.settings.

settings = {
  { id = "quality", type = "text", label = "JPEG quality", default = "85" },
  { id = "keep", type = "checkbox", label = "Keep original", default = true },
  {
    id = "mode",
    type = "select",
    label = "Mode",
    options = {
      { value = "fast", label = "Fast" },
      { value = "best", label = "Best" },
    },
    default = "fast",
  },
}

Supported field types:

Type	UI
text, input	Text field.
password	Obscured text field.
checkbox, toggle, bool	Boolean checkbox row.
select, dropdown	Dropdown.
info, label	Read-only text.

select options may be strings or { value = "...", label = "..." } tables.

Dialogs

waydir.dialog does not return a value. It shows a modal and re-runs the same action with ctx.form filled after submit.

run = function(ctx)
  if not ctx.form then
    waydir.dialog({
      title = "New file",
      fields = {
        { id = "name", type = "input", label = "File name" },
      },
      submit_action = "new_file",
    })
    return
  end

  waydir.write_text(ctx.dir .. "/" .. ctx.form.name, "")
  waydir.refresh()
end

Dialogs are capped with a host-side depth limit to prevent a plugin from opening an endless loop of modal forms.

Icons

icon may be:

• a bundled .svg or .png path relative to the plugin folder;
• an absolute image path;
• a named builtin glyph.

Builtin glyph names:

archive, bell, bookmark, bug, calendar, check, clipboard, clock, code, copy, desktop, download, eye, file, file-audio, file-code, file-image, file-pdf, file-text, file-zip, folder, folder-open, folder-plus, gear, git-branch, hard-drive, image, info, keyboard, list, magic-wand, music, note, palette, pencil, plus, ruler, scissors, search, sliders, terminal, trash, tree, usb, video, warning.

Unknown names fall back to the default plugin glyph.