XMENU(1)

📦 version 4.6.1, in nixos 26.05, nixpkgs unstable

💅 XMENU(1) — the menu utility for X, bestie edition 🎀

okay so first things first: the manual name is xmenu, it lives in the General Commands Manual section, and honestly? it's giving iconic. let's get into it ✨

🌸 NAME 🌸

xmenu — a menu utility for X. that's it, that's the vibe. 💖

⭐ SYNOPSIS ⭐

xmenu [-irw] [-p position] [-x|-X [modifier-]button] [title]

like, that's the whole summoning ritual. 🪄

🦋 DESCRIPTION 🦋

so xmenu is a menu for X, right? it reads a list of newline-separated items from stdin, shows a menu so the user can pick one of the items, and then outputs the item they selected to stdout. that's the entire personality. no cap. 💅

okay the options are as follows, bestie, pay attention:

  • -i — Disable icons. this makes xmenu load faster when you're not using icons. lowkey a speedrun strat. ⚡
  • -p position — Set the position to spawn xmenu. without this option, xmenu spawns next to the cursor. position is a string of the form INTxINT[:MONITOR], where the first INT is the x position and the second INT is the y position. the monitor part between brackets is optional. MONITOR can be a number from 0 to the number of monitors minus 1; or it can be a string like current or cursor. if present, the monitor specifies that the position is relative to the upper left corner of that monitor. if monitor is current or cursor, the monitor to be used is that where the cursor is in. for example, -p 0x0:cursor specifies that xmenu must spawn at the position 0x0 of the monitor where the cursor is in. and -p 100x500:0 specifies that xmenu must spawn at the position 100x500 of the monitor 0. 📍
  • -r — If this option is set, the right mouse button is disabled; so pressing it will not trigger any menu item. sorry right-click girlies, not today. 🙈
  • -w — Asks the window manager to draw a border around the menus. > this option may be buggy in some window managers, specially tiled ones that do not respect window hints. so like, cute idea, risky execution. 💀
  • -x [mod-]button — This option requires an argument of the form mod-button or button; where mod is Mod1 to Mod5, or Alt (equivalent to Mod1), or Super (equivalent to Mod4); and button is the number of a mouse button. when this option is used, xmenu listens to button presses on the root window, and shows the pie menu when the given button is pressed, together with the given modifier, on the root window. for example, invoking xmenu with the option -x Super-3 makes a menu open when clicking with the third mouse button on the root window, or when clicking with the third mouse button together with the Super (Mod4) modifier on any window. this option makes xmenu run continuously; so it should be used when xmenu is invoked in background on a X startup file (like ~/.xinitrc). main character energy fr fr. 👑
  • -X [mod-]button — Just like -x, but also pass the click to the root window (for the window manager to use it, for example). > this option is incompatible with -x. pick a lane, bestie. 🫶

🍓 the item format, a whole mood 🍓

each item read from stdin has the following format:

ITEM := [TABS] [[IMAGE TABS] LABEL [TABS OUTPUT]] NEWLINE

that means that each item is composed by tabs, followed by an optional image specification, followed by tabs followed by a label, followed by more tabs, followed by an output, and ended by a newline. brackets group optional elements. iykyk. ✨

  • the initial tabs indicate the menu hierarchy: items indented with a tab is shown in a submenu of the preceding item not indented. an item without initial tabs is a top-level item. nesting slay. 🌈
  • the image is a string of the form "IMG:/path/to/image.png". it specifies the path to a image file to be shown as icon at the left of the entry. if the path does not begin with "/", "./" or "../", the file is searched on the paths specified in the ICONPATH environment variable. 🖼️
  • the label is the string that will be shown as a item in the menu. an item without label is considered a separator and is drawn as a thin line in the menu separating the item above from the item below. separator era. ➖
  • the output is the string that will be output after selecting the item. if an item does not have an output, its label is used as its output. 💬
  • the newline terminates the item specification. periodt. 🔚

if the argument title is given, the title of the menu window is set to it. 🏷️

🎀 USAGE 🎀

xmenu is controlled by the mouse, but can also be controlled by the keyboard. items can be selected using the arrow keys, Tab (with and without Shift), Home, End, Enter and Esc, and 1-9 keys. items can also be selected by typing the first several characters in it. keyboard girlies rise up. ⌨️💖

  • Home — Select the first item in the menu. ⬆️
  • End — Select the last item in the menu. ⬇️
  • Down — Cycle through the items in the regular direction. 🔄
  • Tab — Cycle through the items in the regular direction. when the type-to-select feature is active, cycle through matching items instead. 🔍
  • Up — Cycle through the items in the reverse direction. ↩️
  • Shift-Tab — Cycle through the items in the reverse direction. when the type-to-select feature is active, cycle through matching items instead. 🔍
  • Right, Enter — Select the highlighted item. ✅
  • Left — Go to the menu above. ⬅️
  • Esc — Go to the menu above or exit xmenu. 🚪

xmenu features the type-to-select selecting style, where typing a string will select the first item matching it. literally so convenient. 💅

additional key bindings can be set at compile time by changing the config.h file. yes, compile time. get your build hat on, babe. 🧚

🌈 RESOURCES 🌈

xmenu understands the following X resources. aesthetic config time, bestie:

  • xmenu.font — The font in which the labels should be drawn. multiple fonts can be added as fallback fonts; they must be separated by a comma. 🔤
  • xmenu.background — The background color of non-selected items in the menu. 🎨
  • xmenu.foreground — The color of the label text of non-selected items in the menu. 🖌️
  • xmenu.selbackground — The background color of selected items in the menu. ✨
  • xmenu.selforeground — The color of the label text of selected items in the menu. 💫
  • xmenu.border — The color of the border around the menu. 🖼️
  • xmenu.separator — The color of the separator between items in the menu. ➖
  • xmenu.gap — The gap, in pixels, between the menus. 📏
  • xmenu.width — The minimum width, in pixels, of the items in the menu. 📐
  • xmenu.height — The size in pixels of the height of a single menu item. 📏
  • xmenu.borderWidth — The size in pixels of the border around the menu. 🔲
  • xmenu.separatorWidth — The size in pixels of the item separator. ➖
  • xmenu.alignment — If set to "left", "center", or "right", text is aligned to the left, center, or right of the menu, respectively. by default, text is aligned to the left. ⬅️
  • xmenu.maxItems — Maximum number of items to be displayed in a menu. if more a menu has more than this number of items, they will be scrolled with arrow buttons. scrolling icon behavior, honestly. 🔽

🧚 ENVIRONMENT 🧚

the following environment variables affect the execution of xmenu. know them, love them:

  • DISPLAY — The display to start xmenu on. 🖥️
  • ICONPATH — A colon-separated list of directories used to search for the location of image files. 🔎

🔥 EXAMPLES 🔥

the following script illustrates the use of xmenu. the output is redirected to sh(1), creating a command to be run by the shell. okay this one's actually so satisfying, watch:

#!/bin/sh

xmenu <<EOF | sh &
Applications
     IMG:./web.png  Web Browser    firefox
     IMG:./gimp.png Image editor   gimp
Terminal (xterm)                   xterm
Terminal (urxvt)                   urxvt
Terminal (st)                      st

Shutdown                           poweroff
Reboot                             reboot
EOF

for example, by selecting “Applications”, a new menu will appear. selecting “Web Browser” in the new menu opens firefox. nested menus eating, no crumbs. 🔥👑

⭐ SEE ALSO ⭐

dmenu(1), 9menu(1), thingmenu(1) — the rest of the menu besties, go say hi. 🫶

and that's the whole page, diva. 💜 the footer says XMENU(1), so like — you're reading the xmenu man page, section 1, General Commands Manual, and the vibe is immaculate. go forth and pipe things into it. 🌸🦋💅

📦 where this page comes from