Quick Panel

The Quick Panel is UniClipboard's keyboard-first entry point: a floating overlay that lists the current space's clipboard history. Arrow-key your way to an item, hit Enter, and it pastes back into the app you came from — without ever bringing the main window forward.

Open and dismiss

Press once to open, press again to close. Esc also dismisses. The panel auto-hides when it loses focus — by design it doesn't try to hold focus indefinitely.

On native Wayland sessions whose compositor cannot provide global hotkeys, bind this command in the compositor instead. It opens the panel when UniClipboard is not running yet, and toggles the existing panel otherwise:

uniclipboard --quick-panel

Omarchy

UniClipboard supports Quick Panel display, desktop-theme following, and pasting back into the previous window in an Omarchy Hyprland session. Use the following steps to replace Omarchy's built-in clipboard-manager shortcut with UniClipboard.

Edit ~/.config/hypr/bindings.lua, remove Omarchy's default Super+Ctrl+V binding, and assign it to UniClipboard:

hl.unbind("SUPER + CTRL + V") -- was: Clipboard manager
o.bind("SUPER + CTRL + V", "UniClipboard quick panel", "uniclipboard --quick-panel")

Hyprland normally reloads the file after it is saved. You can validate it explicitly with:

hyprctl reload
hyprctl configerrors

An empty result from the second command means the configuration is valid. Super+Ctrl+V now opens or closes the Quick Panel while the UniClipboard GUI is running. If the GUI is not running, the command exits with an error instead of starting it. Quick Panel must remain enabled in UniClipboard settings.

macOS and Windows native panel

The macOS and Windows installers include a separate native panel process. It is used by default, and stays resident in the tray with very low usage after the main window is closed. To go back to the previous panel, set the environment variable UC_GPUI_QUICK_PANEL=0 before starting the app. While content is locked the panel shows a locked page and can read no history: the background refuses its requests, and the moment content gets locked the panel also drops every row, thumbnail and preview it was showing. The whole panel then becomes a separate unlock page with only a masked passphrase box (nothing typed there is ever used as a search), so you can type the passphrase and press Enter to unlock right in the panel without opening the main window; a wrong passphrase asks you to try again. The panel refreshes by itself once unlocked.

On Windows, read Ctrl for Cmd in the table below; the default shortcut is Ctrl + Alt + V. The panel pastes by simulating the system's paste keys into the previous window. If that window runs as administrator and UniClipboard does not, Windows drops the simulated keys and the panel reports a missing permission. The first time the background service starts, Windows Firewall may ask to allow network access; it waits for your answer.

This lock covers the app interface only (the main window and the quick panel): the uniclip command-line tool and other clients are not affected. It is also not a defence against a malicious local process, because the client type is declared by the caller and the background trusts the same system user that holds the local connection token. Encryption of data at rest does not depend on this lock.

The right-click menu is replaced by the Cmd + K action list. Alt + Backspace no longer deletes an item; it deletes the previous word in the search box.

Type to search the history, and add conditions with shorthand: #tag, @device, /type, confirmed with Tab. Typing a date or range (such as 9.1-9.15, last week, or 3d) suggests a time condition; in a Chinese interface, pinyin initials also work (for example tp for images, zt for yesterday). Several values of one dimension are OR-ed, different dimensions are AND-ed; there is one time value and a new one replaces it. AND between tags is not supported yet.

When images are the only type, the list becomes a 3×3 grid: arrow keys move between cells, Cmd + 1–9 pastes the matching cell, and the grid scrolls by rows past nine images. Pages for an empty history, a locked state, no results and a disconnected background appear in the list area.

Keyboard controls

The panel is meant to be driven entirely by keyboard. The full set:

Cmd / Ctrl + C and Cmd / Ctrl + V act on whichever item is hovered or keyboard-selected, but defer to the search box's native text selection/paste when you're actively editing the query (a text selection present, or a non-empty query for paste).

Enter simulates a system paste, so the receiving app sees what looks like a regular Cmd/Ctrl+V — rich text and files land at the highest fidelity that the destination app understands.

To paste plain text, hold Option / Alt while confirming an item: press Enter, click an item, or use a Cmd / Ctrl + number shortcut while the modifier is held. UniClipboard writes only the text/plain representation to the system clipboard first; if the item has no plain-text representation, it silently falls back to the normal multi-format paste.

Right-click actions

Right-click any entry — a list row or an image-wall tile — to open a context menu. Right-clicking also selects the entry, so the highlighted item is always the one the menu acts on.

These mirror the per-item actions available on the main window's history cards, so you don't have to open the Dashboard for a one-off copy, favorite, or resend.

Inline preview

When an item is selected, the right pane renders it in the format matching its content type:

Images larger than 8 MB aren't pulled automatically — the pane shows a Load image button instead, so a big original never blocks the preview. Click it to fetch the full image on demand.

The preview is read-only. To put the item back on the system clipboard or paste it, return to the list and hit Enter.

Filtering

The search box is a composite filter bar. Type to match by substring, and layer structured filters that show up as removable chips. Five dimensions are available:

• Type — Text / Rich Text / Image / File (legacy Link / Code chips still resolve).
• Tag — semantic tags such as link or code.
• Source — the device an item was captured on.
• Extension — file extension, for file payloads.
• Time — Today, Yesterday, Last 7 days, Last 30 days, This week, or This month.

Add a chip two ways: click the filter button at the end of the box and pick a value, or type its prefix and choose from the suggestions:

type:image
#link
from:<device>
ext:pdf
time:last_7d

Chips stack — multiple filters are AND-ed — and each has an ✕ to clear it. Plain words outside a chip match as a substring; quoted phrases, boolean operators, and regex are not supported (see Full-text search — Query syntax).

Image filter — thumbnail wall

Image entries in the list normally show a small thumbnail in place of the generic type icon, so you can recognize a specific screenshot without opening the preview. Pin the Image type chip and the list switches to a three-column masonry wall of tile-sized thumbnails sized to each image's aspect ratio — better for skimming several recent captures at once. Arrow-key navigation still follows the underlying time order, so ↑ / ↓ and Cmd/Ctrl + 1–9 behave the same as in the list view.

Filters are in-memory only and don't persist across panel sessions — every reopen starts unfiltered. The panel is a use-and-throw surface, not a workbench.

Customizing the hotkey

The recorded key combination remains the primary trigger. Under Settings → Quick Panel → Double-tap modifier, you can also choose Option/Alt, Control, or Command/Windows/Super and tap that modifier twice to open the panel. Turning this off does not change the recorded shortcut.

On macOS, modifier double-tap requires the separate Accessibility permission. UniClipboard checks the permission without showing a system prompt; use the Open Accessibility settings button to grant it explicitly. Native Wayland sessions are not supported, including sessions that also expose an XWayland DISPLAY; use the recorded shortcut there.

When to use the panel vs. the main window

Troubleshooting

• Recorded hotkey doesn't fire: see Troubleshooting — Clipboard permissions. On macOS confirm Input Monitoring is granted and the app was fully relaunched afterwards.
• Modifier double-tap is disabled on macOS: grant Accessibility from the button beside the setting, then return to UniClipboard. On Linux, native Wayland sessions intentionally report this trigger as unsupported; the recorded hotkey remains available.
• Items you just copied don't appear: the daemon isn't running or the clipboard listener was sandboxed. Check daemon.running and the clipboard logs in uniclip space status.
• A peer's clip never shows up: the sending device may have it gated out — check Devices — Content-type allowlist on that side.