· bmux guides
Vim-Style Browser Navigation Without Breaking Text Fields
Configure Vim-style scrolling, search, and reload in bmux while preserving typing in text fields with conditional shortcuts.
Walkthrough transcript
With conditional Vim bindings configured, use Shift+G to move to the page bottom. Use gg to return to the top. Click a text input and type j and k as ordinary text.
Introduction
bmux can bind j and k to scrolling, gg to the top of a page, and / to find. Add when: pane-not-editing so those keys keep their normal behavior in text fields.
The page actions arrived on September 17, building on conditional pane shortcuts. They are configurable bindings, not a default mode you have to learn before browsing. Start with a few familiar keys and add others only when they help.
The Tart walkthrough above shows a configured page-top/page-bottom sequence, followed by typing j and k normally into a local review field. It uses the real browser keyboard handling with disposable configuration.
Why a global binding can interfere with a website
A single-letter shortcut is convenient on a document and disruptive in a text box. If every j means “scroll down,” you cannot type ordinary words containing that letter.
pane-not-editing applies a shortcut only while the selected page has focus outside editable fields. The address bar, browser prompts, website inputs, and editable page content retain their normal keyboard behavior.
If bmux cannot determine focus safely, it does not intercept the conditional shortcut. That includes unknown focusable controls and closed shadow roots. Selecting ordinary page text does not itself count as editing.
Choose direct keys, prefix bindings, or Click Mode
| Mechanism | Example | Useful for |
|---|---|---|
| Conditional direct shortcut | j scrolls outside an input |
Frequent page actions |
| Multi-key sequence | gg goes to the top |
Familiar ordered key combinations |
| tmux-style prefix | Control+B, then % |
Workspace actions such as splitting |
| Click Mode | Option twice, then a hint | Activating a visible page target |
Vimium's command list is a useful comparison for readers accustomed to keyboard browser navigation. bmux's bindings map keys to its own actions; they are not a full Vim editing language or a claim of extension compatibility.
Keep workspace actions on the prefix when you want a clear separation from typing on the page. Use Click Mode for links and buttons. Direct page bindings are most useful for actions you repeat while reading.
Add scrolling, reload, and search
Open settings with Command+, and edit ~/.config/bmux/config.yaml. Merge this example into the existing keyboard mapping. Avoid creating a second keyboard key or deleting unrelated bindings.
keyboard: shortcuts: j: { action: scroll-down, when: pane-not-editing } k: { action: scroll-up, when: pane-not-editing } d: { action: scroll-half-down, when: pane-not-editing } u: { action: scroll-half-up, when: pane-not-editing } Shift+G: { action: scroll-bottom, when: pane-not-editing } r: { action: reload, when: pane-not-editing } Shift+R: { action: hard-reload, when: pane-not-editing } /: { action: find, when: pane-not-editing } sequences: gg: { action: scroll-top, when: pane-not-editing }The settings reload automatically. You do not need to restart the browser. Two-letter sequences use prefixTimeoutMs as the allowed interval between letters; the default is 1.6 seconds.
If you only want scrolling, start with j, k, and gg. Reload bindings can discard page work just as the ordinary reload button can. Add them when their convenience fits your workflow.
Native Tart capture after the configured Shift+G shortcut. The test checks that the page actually scrolled.
The captured page is at its lower section after the bottom-of-page action. gg returns it to the beginning. This is useful for long reference documents where scrolling is a repeated part of reading.
Check the binding where you actually type
Try the keys on an ordinary page, then click a search or notes field and type the same letters. Also test the address bar and any web editor you use frequently.
Native Tart capture after typing into the local input. This validates the fixture's input behavior, not every web editor.
The input in this capture contains ordinary text after the navigation test. The context condition is what lets the same letters work as page commands and as typed characters in the appropriate place.
Website shortcuts outside editable fields can still conflict. Configured bmux shortcuts take precedence, so pane-not-editing does not automatically resolve every application's keyboard convention. Remove or remap a binding if a site uses it for an action you prefer.
Adapt the configuration
Use the action names from the keyboard reference with keys comfortable on your keyboard. You can use several shortcuts for the same action. Set a particular binding to null to disable it.
Conditional bindings also work for pane actions. For example, a conditional Command+Z binding can zoom the selected pane while retaining Undo in text fields:
keyboard: shortcuts: Cmd+Z: { action: toggle-pane-zoom, when: pane-not-editing }This is an optional remapping, not the default Command+Z behavior. Keep only bindings whose meaning you will remember outside an input.
Vim navigation FAQ
Are these keys enabled by default?
No. The single-letter page bindings in this article are an example configuration. Add the ones you want.
Why does a key sometimes do nothing?
Check focus first. The active element may be editable, an unfamiliar focusable control, or browser UI rather than page content. The conditional action deliberately leaves those contexts alone.
Why does gg fail when I pause?
The second g must arrive within the configured sequence timeout. Adjust prefixTimeoutMs if necessary, remembering that it also controls the tmux-style prefix interval.
Do I need an extension?
No extension is needed for these bmux actions. Combine a small set of conditional navigation keys with native Click Mode and the normal workspace prefix. That gives each part of browsing a predictable keyboard path.