xpopup is a simple X11 popup menu utility. It will read a menu description from standard input, display that menu to the user, and print user’s selection to the standard output.

xpopup is very basic and only provides textual menus. You can (and should) use ASCII art to make it pretty (UTF-8 art, actually). See below for details on how it works.

The primary use case for xpopup is to be invoked by a controlling script that will generate a menu description, and then act upon user selection. Such a thing can be useful on its own, or as an addition to a lightweight window manager such as DWM [1], WMII [2], Awesome [3], and similar others.

You can browse the current sources of xpopup at [4], or download them via mercurial like this:

hg clone http://hg.tx97.net/xpopup

Building xpopup should be as easy as running make, provided that you have x11 and xft development files installed.


It’s easier to show how it works than to describe it, so let’s see an example. Suppose you want to present a menu with two options. Here's what you need to do:

  echo '{o1:Option One} and ...'
  echo '    ... {o2:Option Two}'
} | xpopup

With this menu description xpopup will display a two-line menu with two clickable areas: “Option One” and “Option Two”. Note how {tag:Text} sequences are used to mark clickable parts.

xpopup example #1

If, for example, user will click on letter “w” from “Option Two”, xpopup will exit and print o2 8, which means that 8-th letter from tag o2 was clicked.

If user will click somewhere outside of the popup window, or will press “Esc” or “Q”, xpopup will exit with non-zero status without printing anything.

If you’re wondering why printing not only the tag, but the letter number too -- this is to support ASCII-art sliders, like in the following screenshot.

xpopup example #2


Usage: xpopup [{-nb|-nf|-sb|-sf} color] [-fn font]
              [-pad size] [-pos position]
    -nb color       set normal background color
                    (for example: 'red' or '#ff0000')
    -nf color       set normal foreground color
    -sb color       set selected background color
    -sf color       set selected foreground color
    -fn font        set font (example: 'Courier New-12')
    -pad size       set padding size (in pixels)
    -pos an[offs]   set window's position
                    'an' is anchor, {t|m|b}{l|m|r}
                    for {top|middle|bottom} {left|middle|right}
                    'offs' is x and y offsets (e.g. '-5+10')

Similar software

For a much more powerful (and complex) tool, take a look at dzen [5]. You may also find dmenu [6] useful.


  1. https://dwm.suckless.org/

  2. https://github.com/sunaku/wmii

  3. https://awesomewm.org/

  4. http://hg.tx97.net/xpopup/

  5. http://robm.github.io/dzen/

  6. http://tools.suckless.org/dmenu/