Reference

Settings

Complete reference for all Refbox settings and customization options.

Settings control how Refbox looks, behaves, stores data, and responds to input. This page follows the exact tab and section order used in the app.

Open Settings

Click Settings in the Toolbar.
Or press ⌘ , while Refbox has focus.

Settings tabs overview

Style

App

UI Scale

Adjust the overall scale of the interface. Options: 75%, 90%, 100%, 110%, 125%, and 150%.

Display

Choose the screen that shows Refbox. Each option includes the display name and pixel dimensions.

Hide App from Dock / Hide App from Taskbar

On macOS, hide Refbox from the Dock and Command+Tab switcher. On Windows, hide it from the taskbar and Alt+Tab switcher.

Show on All Desktops

On macOS, keep Refbox visible when you switch virtual desktops or enter full-screen apps.

Box

Position

Choose a side of the screen. Options appear as Left, Right, and Top.

Background

Choose what appears behind Box media: None, Ghost, or Dark.

Show Box Scrollbar

Show or hide the scrollbar in the Box.

Previews

Preview Size

Choose Small, Medium, or Large for the preview Frame attached to the Box.

Preview Position

Choose the position of the attached preview. For a left or right Box, the options are top, middle, and bottom. For a top Box, the same control maps to left, center, and right.

Assets

Asset Corners

Choose the roundness of Assets: None, Small, or Large.

Frames

Default Sketch Background

Choose the initial background for new Sketch drawings: White, Dark, or None.

Group Background

Choose what appears behind Group content: None, Ghost, or Dark.

Masonry

Auto Column Width

Set the maximum column width for Auto Column layouts in the Box, Groups, and Gallery. Options: Small, Medium, and Large.

Behavior

App

Visibility

Choose when Refbox is visible:

All Apps: Refbox stays visible while you use any app.
Only Selected Apps: Refbox only shows while a saved app is in the foreground.
All Apps Except Selected: Refbox hides while a saved app is in the foreground.

Your Apps

For either selected-app mode, add an app from the list of open apps. Refresh the list when an app is missing. Remove a saved app with its remove button.

Select What's Hidden

For either selected-app mode, choose Frames Only, Sidebar Only, or Sidebar and Frames. In the excluded mode, the selected parts hide while you use a saved app. In the only-selected mode, they hide while you use any other app.

Clicking Refbox reveals its hidden parts. Global Show/Hide still controls the complete app.

Box

Keep Toolbar Open

Always show the Toolbar without requiring pointer hover.

Auto Hide

Hide the Box when the pointer moves away.

Auto Hide Method

Choose Edge Hover or Reveal Button as the method used to reveal an auto-hidden Box.

Maintain Width

Keep the same Box width when you switch Boxes. When off, each Box remembers its own width.

Zoom Previews

Show enlarged previews while you hold Alt/Option over Box Assets.

Auto-Preview New Items

Show previews of newly created Notes, Sketches, and Palettes.

Frames

Default Group Mode

Choose the initial Group Frame layout: Grid, Column, or Masonry.

3D Orbit Method

Choose Turntable, Pole Limited, or Trackball rotation for 3D Frames.

Assets

Autoplay Videos

Automatically play video Assets across Refbox.

Import Quality

Choose Low, Medium, or High image-import quality to balance storage and detail.

Drop Location

Choose where newly dropped Assets are placed in a Box Section: Section Bottom or Mouse Position.

URL Import

Choose the default method for web URLs: Ask Me, Link, or Screenshot.

Text Paste

Choose Plain Text or Formatted. Formatted paste keeps formatting when available, including Markdown syntax.

Colors

Color Format

Choose HEX, HEX no #, RGB, or HSL. This controls the screen color picker's clipboard output and the initial label and copy format for new Palettes. Existing Palettes keep their own format.

Paste as Palette

When on, pasted text made entirely of supported color values becomes a Palette instead of a Note. Hold Shift while you click Paste From Clipboard to skip Palette conversion for one paste.

Show Color Values

Choose whether new Palettes label each color with its value. Change one existing Palette from its Frame context menu.

The Toolbar tab says Choose what actions appear in your Toolbar and shows a live preview. Toggle actions in this exact order:

Hide Box
Add File
Paste From Clipboard
Add Note
Add Sketch
Add Palette
Add Section
Add Group
Color Picker
Close Frames
Export Box
Box Position
Auto Hide Box
Keep Toolbar Open
View Mode
Gallery View

Settings and the Boxes Menu remain in the Toolbar. An unlock action also appears automatically when one or more Frames are locked.

Controls

Global Shortcuts

Global shortcuts trigger even when Refbox does not have focus. They can override the same shortcut in another app. Each shortcut can be enabled, disabled, or changed.

They appear in this order:

Show/Hide App — ⌘ ⌥ S
Show/Hide Gallery — ⌘ ⌥ A
Color Picker — ⌘ ⌥ I
Paste From Clipboard — ⌘ Shift ⌥ V and disabled by default

Mouse

Scroll Sensitivity

Adjust how strong scrolling and zooming feel, from 0.1x to 5x in 0.1x steps.

Zoom/Scroll

Choose Zoom or Scroll for each context in this order:

Frames
Groups
Gallery

Holding Cmd on macOS or Ctrl on Windows temporarily performs the opposite action.

Frames

Scaling

Choose Free or Fixed media scaling. Hold Shift while resizing to use the opposite behavior.

Box Shortcuts

The Settings panel shows these fixed Box controls:

Quick Magnify — Alt/Option
Native File Drag — Shift + drag
Drag Scroll — Cmd/Ctrl + drag

Choose See All Shortcuts to open the complete Shortcuts reference.

Data

Import & Export

Export Boxes

Export one or more Boxes to a .refbox file for transfer or backup.

Import Boxes

Choose and preview a .refbox file before importing it.

Access Control

Command Line Access

Let the refbox command-line tool read and change your Boxes. Enabling it installs the command on your PATH. Restart terminals that were already open, then run refbox status.

If Refbox detects a missing, stale, or off-PATH command, this section shows a repair message and Try again. If another file already uses the installation path, remove that conflict before you retry.

See Command Line Access, the CLI Reference, and MCP Setup for complete instructions.

Trash

Empty / Restore

Deleted Boxes and Assets remain in the Trash for up to 30 days. Each row shows its name, location, deletion age, and disk size. Choose Restore on one row to return it, or Empty to permanently remove all Trash contents and free disk space.

Emptying the Trash cannot be undone. Refbox can also remove the oldest Trash media before 30 days if Trash media exceeds 2 GB.

Restored Boxes return at the end of the Box list. A restored Asset returns to its Box but does not restore deleted Frames or Group membership. If its old Section no longer exists, it returns outside all Sections.

Account

The Account tab shows the signed-in license and device.

Trial License

Trial users see the remaining days, expiration date, Purchase License, and Sign in again actions. Sign in again opens the browser and checks the same email for a paid license. An optional Enter a license key instead field remains available for older purchases.

Identity

The identity panel shows:

Email
License Key, hidden by default with reveal and copy controls
This device

Account Actions

Sign out of this device returns Refbox to the sign-in screen and frees the device slot after confirmation.
Manage Online opens the Refbox account page.