mini-posframe

mini-posframe mirrors the active minibuffer inside a child frame (posframe). It was built on top of posframe, with the intent of providing a consistent, session-scoped minibuffer experience in Spacemacs.

mini-posframe.mov

⚠️ Compatibility: mini-posframe was built and tested for Spacemacs with Evil workflows. It includes advice for Helm integration. It has no advice for Ivy, Counsel, Vertico, or Doom Emacs — it will likely break in those workflows. Contributions for additional compatibility are welcome.

Features

• Displays minibuffer input inside a posframe instead of the echo area.
• Tracks the cursor visually with a fake cursor overlay.
• Automatically hides the real minibuffer for a distraction-free look.
• Session-scoped: posframe appears only during minibuffer usage and is cleaned up afterwards.
• Includes optional compatibility fixes for helm-posframe to keep behavior consistent.

Customization

All user options can be customized via:

M-x customize-group RET mini-posframe RET

Positioning

(defcustom mini-posframe-position 'top-center
  "Where to display the mini-posframe."
  :type '(choice
          (const :tag "Top center" top-center)
          (const :tag "Center" center)
          (const :tag "Bottom center" bottom-center)
          (const :tag "Top left" top-left)
          (const :tag "Left" left)
          (const :tag "Bottom left" bottom-left)
          (const :tag "Top right" top-right)
          (const :tag "Right" right)
          (const :tag "Bottom right" bottom-right)))

You can choose any of the above symbols. The top/bottom positions respect vertical fringes, and left/right positions respect horizontal fringes.

positioning.mov

See Hotkeys for positioning helpers.

Fringes

• mini-posframe-vertical-fringe (default 0.10) – fraction of parent frame height to offset vertically.
• mini-posframe-horizontal-fringe (default 0.05) – fraction of parent frame width to offset horizontally.

Size

• mini-posframe-width (default 60) – width in characters.
• mini-posframe-height (default 1) – fixed height in lines. When set to 1, height is determined dynamically from content.
• There’s an interactive resize helper function, mini-posframe-resize that allows you to set it dynamically.

Appearance

• mini-posframe-font-size – relative scale factor for font height.
• mini-posframe-border-width – internal border width (pixels).
• mini-posframe-parameters (alist) – extra frame parameters passed to posframe-show. By default only (undecorated . nil) is set.

Faces:

• mini-posframe-face – controls text appearance.
• mini-posframe-border-face – controls border appearance.

Commands

• mini-posframe-mode – global minor mode to enable minibuffer mirroring.
• mini-posframe-reset – forcibly reset and restart the mode.

Cleanup hooks ensure state resets when minibuffer exits.

Helm Posframe Compatibility

Optional integration keeps behavior consistent with helm-posframe:

• Defensive advice around helm-ff-delete-char-backward-with-subkeys to prevent nil-command execution.
• Advice loaded only if helm-posframe is present.
• Lifecycle hooks ensure it applies only when helm-posframe is enabled.

⚠️ Not tested with Ivy, Counsel, Vertico, or other completion frameworks.

Defaults Summary

• Position: top-center (10% from top, centered horizontally).
• Width: 60 characters.
• Height: dynamic (1 → auto-fit).
• Font scale: 1.4 relative to default.
• Border width: 3.
• Parameters: (undecorated . nil)
  • Set in order to get the rounded borders on MacOS. Set to (undecorated . t) for undecorated on other OS’s.

Example Configuration

Here is an example of configuring mini-posframe to display in the top-right, with mini-posframe-font-size=1 and width=100 characters:

Using setq:

(setq mini-posframe-position 'top-right
      mini-posframe-font-size 1
      mini-posframe-width 100)

(mini-posframe-mode 1)

Using use-package:

(use-package mini-posframe
  :load-path "~/path/to/mini-posframe"
  :custom
  (mini-posframe-position 'top-right)
  (mini-posframe-font-size 1)
  (mini-posframe-width 100)
  :config
  (mini-posframe-mode 1))

Ex 1:

---

---

Ex 2:

---

---

Installation

Spacemacs

Add it as a recipe in dotspacemacs-additional-packages:

(mini-posframe :location (recipe :fetcher github :repo "JoshTRN/mini-posframe"))

Or place it in a private layer and require it manually.

Hotkeys

I set up some personal hotkeys that map directionally onto the left hand for quick positioning:

Layout (on qwerty):

↖️ q	⬆️ e	↗️ t	← Top row — top-left, top-center, top-right
⬅️ a	⬤ d	➡️ g	← Middle row — center-left, center, center-right
↙️ z	⬇️ c	↘️ b	← Bottom row — bottom-left, bottom-center, bottom-right

Here’s how the bindings map under SPC o m:

(spacemacs/declare-prefix "om" "mini-posframe")

(spacemacs/set-leader-keys
  "omr" #'mini-posframe-resize

  ;; Top row
  "omq" #'mini-posframe-top-left
  "ome" #'mini-posframe-top-center
  "omt" #'mini-posframe-top-right

  ;; Middle row
  "oma" #'mini-posframe-center-left
  "omd" #'mini-posframe-center
  "omg" #'mini-posframe-center-right

  ;; Bottom row
  "omz" #'mini-posframe-bottom-left
  "omc" #'mini-posframe-bottom-center
  "omb" #'mini-posframe-bottom-right)

This layout allows for positional muscle memory. The left-hand keys directly mirror the posframe’s on-screen placement, making quick repositioning natural and fluid.

Vanilla Emacs

Clone into your load-path and enable:

(use-package mini-posframe
  :load-path "~/path/to/mini-posframe"
  :config
  (mini-posframe-mode 1))

License

This project is licensed under the GNU General Public License v3.0.

See the LICENSE file for full text.