1# Keybindings
2
3Dumber uses modal keybindings inspired by Zellij. Press a mode activation key, then use action keys within that mode.
4
5## Mode Activation
6
7| Mode | Key | Purpose |
8|------|-----|---------|
9| Pane Mode | `Ctrl+P` | Split, close, focus panes |
10| Tab Mode | `Ctrl+T` | Create, close, switch tabs |
11| Vim Mode | `Ctrl+Y` | Scroll, navigate headings, and focus page inputs with Vim-style commands; arrow keys stay native and page focus stays inside the page while other app shortcuts wait until exit |
12| Resize Mode | `Ctrl+N` | Resize pane splits |
13| Session Mode | `Ctrl+O` | Session management |
14
15Press `Escape` or `Enter` to exit any mode.
16`Ctrl+Y` can activate Vim Mode even when a page input is already focused, so you can use Vim commands without first moving focus away from the editor.
17
18Keybinding tables use uppercase letters as visual labels for unshifted letter keys. In config, use lowercase (for example, `["w"]` for Pane Mode eject). Shifted keys are shown with an explicit `Shift+` prefix.
19
20## Pane Mode (`Ctrl+P`)
21
22| Action | Keys |
23|--------|------|
24| Split right | `→`, `R` |
25| Split left | `←`, `L` |
26| Split up | `↑`, `U` |
27| Split down | `↓`, `D` |
28| Stack pane | `S` |
29| Close pane | `X` |
30| Move to tab | `M` |
31| Move to next tab | `Shift+M` |
32| Eject to window | `W` |
33| Focus right | `Shift+→`, `Shift+L` |
34| Focus left | `Shift+←`, `Shift+H` |
35| Focus up | `Shift+↑`, `Shift+K` |
36| Focus down | `Shift+↓`, `Shift+J` |
37| Consume/expel left | `[` |
38| Consume/expel right | `]` |
39| Consume/expel up | `{` |
40| Consume/expel down | `}` |
41| Confirm | `Enter` |
42| Cancel | `Escape` |
43
44## Tab Mode (`Ctrl+T`)
45
46| Action | Keys |
47|--------|------|
48| New tab | `N`, `C` |
49| Close tab | `X` |
50| Next tab | `L`, `Tab` |
51| Previous tab | `H`, `Shift+Tab` |
52| Rename tab | `R` |
53| Confirm | `Enter` |
54| Cancel | `Escape` |
55
56## Vim Mode (`Ctrl+Y`)
57
58Vim Mode is an explicit Vim-style navigation mode for the active pane only. Its frame uses `workspace.styling.vim_mode_color`, a bottom-left `VIM MODE` toast stays visible while the mode is active, and a shortcut legend appears after 500 ms. Set `workspace.styling.mode_legend` to `always` or `off` to change the legend timing. The mode exits automatically when focus moves into the omnibox, find bar, overlays, or an editable element inside the page. The default `timeout_ms` is `0`, so Vim Mode does not auto-time out unless you configure one. Arrow keys continue to flow through the browser engine's native page-navigation path while Vim Mode is active, while other app-level shortcuts stay suspended until you leave the mode. `Ctrl+Y` remains available when an editable page control is already focused.
59
60CEF and WebKit execute Vim Mode scroll commands (`h/j/k/l`, `Shift+J/K`) with the shared `BuildPageScrollByJS` resolver. Each step starts under the viewport center, walks up through ancestors that can move in the requested direction, and hands scrolling to the document when a nested container reaches its boundary. Cross-origin frame contents remain best-effort.
61
62`gi` focuses the next visible, editable page input. With no eligible input focused it starts at the first one; repeated `gi` commands cycle through the inputs. `]]` and `[[` move through visible `h1`–`h6` headings and outline the selected heading with the current Dumber theme accent. `Enter` activates the first link inside the selected heading, or a link wrapping that heading, then leaves Vim Mode; without an associated link, it only leaves the mode. `Escape` leaves without activation. When a page input is focused, `Tab` and `Shift+Tab` keep focus traversal inside the page; traversal stops safely at the page boundaries instead of moving into the host window. These live input, heading, activation, and page-focus actions currently use the CEF engine path; the WebKit fallback supports Vim scrolling but not these semantic actions yet.
63
64| Action | Keys |
65|--------|------|
66| Scroll left | `H` |
67| Scroll down | `J` |
68| Scroll up | `K` |
69| Scroll right | `L` |
70| Scroll down fast | `Shift+J` |
71| Scroll up fast | `Shift+K` |
72| Focus next page input | `gi` |
73| Next heading | `]]` |
74| Previous heading | `[[` |
75| Page focus traversal | `Tab`, `Shift+Tab` |
76| Activate selected heading link and exit | `Enter` |
77| Exit without activation | `Escape` |
78
79## Resize Mode (`Ctrl+N`)
80
81| Action | Keys |
82|--------|------|
83| Increase left | `H`, `←` |
84| Increase down | `J`, `↓` |
85| Increase up | `K`, `↑` |
86| Increase right | `L`, `→` |
87| Decrease left | `Shift+H` |
88| Decrease down | `Shift+J` |
89| Decrease up | `Shift+K` |
90| Decrease right | `Shift+L` |
91| Increase (smart) | `+`, `=` |
92| Decrease (smart) | `-` |
93| Confirm | `Enter` |
94| Cancel | `Escape` |
95
96## Session Mode (`Ctrl+O`)
97
98| Action | Keys |
99|--------|------|
100| Session manager | `S`, `W` |
101| Confirm | `Enter` |
102| Cancel | `Escape` |
103
104## Global Shortcuts
105
106These work outside modal modes:
107
108| Action | Keys |
109|--------|------|
110| Toggle floating pane | `Alt+F` |
111| Toggle History sidebar (native GTK sidebar panel only). Ctrl+H may conflict with the browser's default History shortcut; behavior can vary by browser. | `Ctrl+H` |
112| Toggle Favorites sidebar (native GTK bookmarks panel) | `Ctrl+B` |
113| Toggle current page favorite/bookmark | `Ctrl+D` |
114| Toggle Config system view in right split | unbound by default |
115| Close pane (or release floating pane) | `Ctrl+W` |
116| Next tab | `Ctrl+Tab` |
117| Previous tab | `Ctrl+Shift+Tab` |
118| Consume/expel left | `Alt+[` |
119| Consume/expel right | `Alt+]` |
120| Consume/expel up | `Alt+{` |
121| Consume/expel down | `Alt+}` |
122
123- `Alt+F` is the only floating-pane shortcut enabled by default.
124- `Alt+F` toggles floating visibility and keeps floating pane state intact.
125- `Ctrl+H` toggles the native GTK history sidebar. The sidebar shows browsing history grouped by day with search/filter, keyboard navigation (arrows, Home/End, Ctrl+arrows for day jumps), and activation modes (Enter to navigate while keeping the sidebar open, Ctrl+Enter to navigate while keeping the sidebar open, Shift+Enter to open in a new split). If the native sidebar is unavailable, the shortcut returns an error instead of falling back to `dumb://history`.
126- `Ctrl+B` toggles the native GTK Favorites sidebar. Search matches favorite titles, URLs, and tag names. `Tab`/`Shift+Tab` traverse search, every tag filter, and the favorites list; arrow keys navigate favorites once the list is focused. The `+` at the right end of the tag-filter row creates a named tag. With a favorite selected in the list, `+` opens its tag binding controls. `Enter` and `Ctrl+Enter` open the selected favorite in the current pane while keeping the sidebar open; `Shift+Enter` opens it in a new split. Inside the sidebar, `a` adds, `e` edits, `s` opens shortcut mode, `Delete` starts delete confirmation, `/` focuses search, `Esc` clears/cancels/closes, `r` reloads, and `c` clears search and filters.
127- `Ctrl+D` toggles the active page as a favorite/bookmark. Favorite shortcut metadata can be assigned in the sidebar, but global `Alt+1..9` remains tab switching.
128- `Ctrl+W` closes the active pane; when the floating pane is active, it fully releases that floating session.
129- Any URL shortcut (for example `Alt+G`) must be defined explicitly in `workspace.floating_pane.profiles`.
130- Floating profile shortcuts support modifier combos with `ctrl`, `shift`, and `alt` (for example `ctrl+shift+y` or `ctrl+alt+m`).
131
132Warning: some `Alt+<key>` combinations may conflict with browser-engine shortcuts, website handlers, or your desktop environment.
133If a shortcut does not trigger in Dumber, choose a different keybinding.
134
135For details, see [Floating Pane](./floating-pane.md).
136
137## Customization
138
139All keybindings can be customized in `~/.config/dumber/config.toml`:
140
141```toml
142[workspace.pane_mode.actions]
143split-right = ["arrowright", "r"]
144close-pane = ["x", "q"]
145
146[workspace.vim_mode]
147activation_shortcut = "ctrl+y"
148timeout_ms = 0
149
150[workspace.vim_mode.actions.vim-scroll-left]
151keys = ["h"]
152
153[workspace.vim_mode.actions.vim-scroll-down]
154keys = ["j"]
155
156[workspace.vim_mode.actions.vim-scroll-up]
157keys = ["k"]
158
159[workspace.vim_mode.actions.vim-scroll-right]
160keys = ["l"]
161
162[workspace.vim_mode.actions.vim-scroll-down-fast]
163keys = ["shift+j"]
164
165[workspace.vim_mode.actions.vim-scroll-up-fast]
166keys = ["shift+k"]
167
168[workspace.vim_mode.actions.focus-input]
169keys = ["gi"]
170
171[workspace.vim_mode.actions.heading-next]
172keys = ["]]"]
173
174[workspace.vim_mode.actions.heading-prev]
175keys = ["[["]
176
177[workspace.shortcuts.actions.close-pane]
178keys = ["ctrl+w"]
179
180[workspace.shortcuts.actions.toggle-floating-pane]
181keys = ["alt+f"]
182
183[workspace.shortcuts.actions.toggle-history-systemview]
184keys = ["ctrl+h"]
185
186[workspace.shortcuts.actions.toggle-favorites-sidebar]
187keys = ["ctrl+b"]
188
189[workspace.shortcuts.actions.toggle-current-page-favorite]
190keys = ["ctrl+d"]
191
192[workspace.shortcuts.actions.toggle-config-systemview]
193keys = []
194
195[workspace.floating_pane]
196width_pct = 0.82
197height_pct = 0.72
198
199[workspace.floating_pane.profiles.google]
200keys = ["alt+g"]
201url = "https://google.com"
202
203[workspace.floating_pane.profiles.github]
204keys = ["alt+h"]
205url = "https://github.com"
206```
207
208See [Configuration](../config/index.md) for full details.