A Firefox extension for middle-click drag panning across zoomed pages and viewports.
1:1 Hand-Tool Pan · Pinch-Zoom Support · Linux uinput Bridge · Kinetic Momentum · Container Scrolling · Domain Blacklist
Firefox does not provide a reliable way to pan a pinch-zoomed page with a mouse. Built-in scrolling methods move only the page layout, so horizontal movement stops when the page itself has no overflow, and the visual viewport offset cannot be set directly.
AltPan adds a drag-to-pan gesture, assigned to middle-button drag by default. While the button is held and the mouse moves, the page pans horizontally and vertically at the same speed as the pointer, including when the page is zoomed in.
%%{init: {"flowchart": {"curve": "basis", "nodeSpacing": 36, "rankSpacing": 56, "padding": 18, "subGraphTitleMargin": {"top": 14, "bottom": 14}}}}%%
flowchart TD
Act(["🖱️ User action<br/>middle-button drag"])
Dec{"visualViewport.scale<br/>> 1.05 ?"}
subgraph native["Native path"]
direction TB
Bridge["Native Bridge<br/><i>IPC</i>"]
Wheel["High-resolution wheel<br/><small>uinput via IPC</small>"]
APZ["Firefox APZ Pan<br/><small>compositor thread</small>"]
Bridge --> Wheel --> APZ
end
subgraph dom["DOM path"]
direction TB
Container["DOM / Container"]
ScrollBy["scrollBy()<br/><small>main thread</small>"]
Layout["Layout Scrolled<br/><small>repaint</small>"]
Container --> ScrollBy --> Layout
end
Act --> Dec
Dec -->|"YES"| Bridge
Dec -->|"NO"| Container
classDef trigger fill:#E3F2FD,stroke:#1565C0,stroke-width:2px,color:#0D47A1;
classDef decision fill:#FFF8E1,stroke:#F9A825,stroke-width:2px,color:#7A4F00;
classDef nativeNode fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20;
classDef domNode fill:#E7F0FA,stroke:#1E6BB8,stroke-width:2px,color:#10395E;
classDef outcomeN fill:#2E7D32,stroke:#1B5E20,stroke-width:3px,color:#FFFFFF;
classDef outcomeD fill:#1E6BB8,stroke:#10395E,stroke-width:3px,color:#FFFFFF;
class Act trigger;
class Dec decision;
class Bridge,Wheel nativeNode;
class Container,ScrollBy domNode;
class APZ outcomeN;
class Layout outcomeD;
style native fill:#F4FBF5,stroke:#66BB6A,stroke-width:2px;
style dom fill:#F5F9FD,stroke:#7FA9D4,stroke-width:2px;
You need both the Firefox extension and the Linux native helper.
Clone the repository and run the installer script:
git clone https://github.com/BeyondMagic/altpan.git
cd altpan
./install_host.shThis writes the native host manifest to ~/.mozilla/native-messaging-hosts/ and ~/.config/mozilla/native-messaging-hosts/, and marks native/altpan_host.py executable.
Note
The helper writes to /dev/uinput using Python's evdev package. If your user account can't open /dev/uinput, add yourself to the input group and log back in:
doas usermod -aG input $env.USERsudo usermod -aG input $USERCopy altpan.xpi into your Firefox profile's extensions/ directory:
cp altpan.xpi ~/.config/mozilla/firefox/<your-profile>/extensions/altpan@terra.local.xpiYou can also open about:addons, click the gear icon, pick "Install Add-on From File...", and select altpan.xpi.
Open about:debugging#/runtime/this-firefox, click "Load Temporary Add-on...", and pick manifest.json from the repository folder.
Click the AltPan icon in your toolbar to change any setting:
| Setting | Default | Description |
|---|---|---|
| Enable AltPan | true |
Turns AltPan on or off globally. |
| APZ Native Bridge | Live Status | Shows whether the /dev/uinput helper is connected. |
| Modifier Key | None |
Key held during drag: None (middle-click only), Alt, Shift, Ctrl, or Meta. |
| Sensitivity | 0.5x |
Drag speed multiplier (from 0.2x to 2.5x). |
| Kinetic Momentum | Enabled |
Keeps scrolling briefly after you let go of the mouse button. |
| Coast Duration | Normal (0.92) |
How fast momentum slows down (Crisp: 0.88, Normal: 0.92, Floaty: 0.96). |
| Excluded Domains | figma.com, miro.com, maps.google.com |
Sites where AltPan stays out of the way (plus a "+ Current Site" button). |
This project is licensed under LGPLv3.