Skip to content
react-ui-os

HUD overlay

The HUD is the small, non-interactive floating indicator that confirms a momentary action: the analogue of the macOS volume / brightness pill or the Windows volume slider. It lives in the center, fades in, sits, fades out, and never blocks input. The library wires it into the actions that benefit (window snap, maximize / restore) and exposes the imperative API so consumers can fire their own.

Drag a window to the edge and release. The snap HUD lights up briefly Open in new tab ↗

Imperative API

Section titled “Imperative API”
import { showHud, hideHud } from "@react-ui-os/desktop";


showHud({
  title: "Maximized",
  // optional second line
  sublabel: "Hello window",
  // optional 0..1 bar, handy for volume / brightness analogues
  progress: 0.42,
  // optional icon node (use your icon kit)
  icon: <VolumeIcon />,
  // optional accent override (defaults to the theme accent)
  accent: "#22c55e",
  // optional hold-before-fade in ms (default 1100)
  duration: 800,
});


hideHud();

Firing again before the previous HUD fades replaces it in place: repeated brightness taps coalesce into a single floating indicator that updates its progress bar smoothly, the way an OS handles volume keys.

Built-in calls

Section titled “Built-in calls”

The library fires the HUD for these actions out of the box:

ActionHUD title
Drag window to top edge → maximize via snapMaximized
Drag window to left/right edge → halveSnapped Left/Right
Drag window to corner → quarterTop Left Quarter, etc.
Cmd/Ctrl + ↑ or double-click title bar (maximize)Maximized
Cmd/Ctrl + ↓ or Esc (restore from maximize)Restored
Cmd/Ctrl + ←/→ (snap chord)Snapped Left/Right

Replace any of them by calling showHud(...) in your own handler after the action. The store always shows the latest payload.

Visual contract

Section titled “Visual contract”
  • Centered: top: 50%; left: 50%; translate(-50%, -50%).
  • Backdrop-blurred surface, theme-accent for the icon and the optional progress bar.
  • Enters with a small scale-up + fade-in, exits in reverse.
  • pointer-events: none: the HUD never traps input. The user can keep dragging, typing, clicking through.
  • role="status" aria-live="polite": screen readers announce the title without interrupting.

When NOT to use it

Section titled “When NOT to use it”
  • For anything actionable: use a toast with a button.
  • For state that persists: surface it inline in the window.
  • For background work: notifications are the right home.

The HUD is for the moment you complete an action and want an unobtrusive “yes, that happened.” Nothing more.

See also

Section titled “See also”