Perch is deliberately quiet: after setup you mostly just glance at it. This page covers the handful of surfaces you’ll actually interact with.
The expanded panel
Hover the notch (in dynamic mode, hover where it would be) and it expands into a panel: a slim top bar of icon buttons — one per page — and the current page’s widgets below, arranged on a grid. Default is one widget on the left, one on the right.
Pages are yours: create them, name them, and place any widget from any
installed package into any slot in Settings → Pages. Packages never
declare pages — placement is always your call.
The priority stack
Settings → Priority is one continuous drag list of every widget that can
compete for the notch itself — pills, peeks, and transients from all
packages, builtin and Workshop alike — split by a divider:
- Above the divider = enabled. Order is priority (within the urgency rules: transients outrank events, events outrank ambients).
- Below the divider = disabled. Dragging a row across the divider is the enable/disable act — there is no separate toggle anywhere.
Two details worth knowing:
- Disabling a widget in the stack only stops uninvited notch presence. If you placed it on a page, it stays on that page — placement is a separate decision, and for expanded widgets placement is enablement.
- A package whose widgets are all below the divider is fully stopped: its Lua never runs, costing exactly nothing.
Themes
Settings → Appearance lists every installed theme. Selection is
enablement — exactly one theme is active, and the rest are inert data. The
permanent fallback is perch black; a broken theme can never take the
overlay down. Themes recolor surfaces, text, accents, and shadows — the
geometry and motion are always Perch.
Transients
Volume, brightness, night light, connect/disconnect events, low battery, and downloads appear as transients: they widen the notch, do their job, and retract on their own. They outrank everything briefly, then restore whatever was showing before, exactly as it was.
The tray
Perch lives in your system tray. Click opens Settings; right-click offers Settings, Help, Credits, and Quit. Quitting removes the notch entirely — Perch runs nothing in the background once quit.
That’s the whole user surface. The rest of these docs are about building mods — which is where Perch gets fun.