ghostty scrollbars on linux (gtk)

Ghostty terminal with native GTK scrollbar on Linux

Status:	⚠️ Experimental - main branch only (post-1.2.0)
Merged:	October 17, 2025 via PR #9245
Configuration:	`scrollbar = system` (default) or `scrollbar = never`
Build Required:	Must compile from `main` branch after Oct 17, 2025
Integration:	Follows GTK theme and system scrollbar preferences

native gtk scrollbar support brings visual scrollback navigation to ghostty on linux, with seamless desktop environment integration.

⚠️ Important: Experimental Feature This feature is not yet in a stable release. It only exists in development builds from the main branch. You must build ghostty from source to use scrollbars. A bug fix was issued one day after merge, indicating this feature is still stabilizing.

overview

ghostty’s gtk scrollbar support, merged on october 17, 2025, adds native visual scrollbars to the linux version. this long-awaited feature (closing issue #111) provides:

visual position indicator showing location in scrollback buffer
mouse-driven navigation with click and drag scrolling
gtk theme integration matching your desktop environment colors
system preferences respecting gnome/kde scrollbar behavior
smooth scrolling with native gtk animations
minimal performance impact using efficient rendering

the implementation wraps the terminal surface in a GtkScrolledWindow widget that binds to the terminal’s scrollback metadata, automatically syncing scroll position as you navigate history.

📝 Note on Source Documentation The in-source config documentation at Config.zig:1232 is outdated and still claims “This only applies to macOS currently. GTK doesn’t yet support scrollbars.” This comment has not been updated since the October 17 merge.

for comprehensive ghostty configuration, see the main configuration guide.

prerequisites

requirement: development build

scrollbar support requires building from the main branch:

cd ~/src/ghostty
git checkout main
git pull origin main

# ensure you have commits from Oct 17, 2025 or later
git log --oneline | head -5

look for commit 063070915 or later in the output.

build ghostty from source

follow the ubuntu build guide to compile from source:

# build with scrollbar support
zig build -Doptimize=ReleaseFast

# install
sudo zig build -Doptimize=ReleaseFast --prefix /usr/local install

verify scrollbar support

check if your build includes scrollbar support:

ghostty --version

# the build should be from main branch, post-1.2.0

configuration

basic setup

add to ~/.config/ghostty/config:

# enable scrollbars (default behavior)
scrollbar = system

configuration options

two options control scrollbar visibility:

system (default)

follows your desktop environment’s scrollbar preferences:

scrollbar = system

behavior:

gnome: overlay scrollbars appear on hover/scroll (configurable in gnome tweaks)
kde plasma: follows system settings → appearance → application style
gtk settings: respects org.gnome.desktop.interface overlay-scrolling
traditional: always visible if overlay scrolling is disabled

never

completely hides scrollbars:

scrollbar = never

useful for:

minimalist setups preferring keyboard-only navigation
tiling window managers with minimal ui preferences
remote sessions where scrollbar rendering adds overhead
screenshots requiring clean, distraction-free terminals

system integration

gnome desktop

control scrollbar behavior via gnome tweaks:

# install gnome tweaks if needed
sudo apt install gnome-tweaks

# or via gsettings
gsettings set org.gnome.desktop.interface overlay-scrolling true   # overlay mode
gsettings set org.gnome.desktop.interface overlay-scrolling false  # always visible

gnome tweaks: general → show scrollbars → choose mode

kde plasma

settings → appearance → application style → configure gtk applications → scrollbar behavior

gtk configuration

direct gtk3 settings:

# overlay scrollbars (appear on hover)
gsettings set org.gnome.desktop.interface overlay-scrolling true

# traditional scrollbars (always visible)
gsettings set org.gnome.desktop.interface overlay-scrolling false

usage

mouse interaction

scrollbar supports full mouse interaction:

hover: reveals scrollbar (overlay mode)
click: jumps to approximate position
drag: smoothly scrolls through history
wheel: scroll while hovering for fine control

visual indicators

the scrollbar provides visual feedback:

thumb size: indicates visible content proportion (based on len field from PageList.Scrollbar)
thumb position: shows location in scrollback buffer (based on offset and total fields)
highlighting: active state when interacting
theme colors: matches gtk theme automatically
vertical only: horizontal scrollbar is always disabled in the blueprint (hscrollbar-policy: never)

combined with keyboard

scrollbars complement keyboard navigation:

# prompt jumping (requires shell integration)
keybind = ctrl+shift+up=jump_to_prompt:-1    # previous prompt
keybind = ctrl+shift+down=jump_to_prompt:1   # next prompt

# page navigation
# use page up/page down keys (built-in)

# smooth scrolling
# use mouse wheel (built-in)

see configuration guide for complete keybinding setup.

theme integration

automatic theming

scrollbars inherit your gtk theme automatically:

catppuccin mocha: dark purple/lavender scrollbar
catppuccin latte: light beige/pink scrollbar
adwaita dark: dark gray scrollbar
adwaita light: light gray scrollbar

custom gtk css

customize scrollbar appearance with gtk css:

# in ghostty config
gtk-custom-css = ~/.config/ghostty/custom.css

example ~/.config/ghostty/custom.css:

scrollbar {
  background: transparent;
}

scrollbar slider {
  background: rgba(255, 255, 255, 0.3);
  border-radius: 8px;
  min-width: 8px;
  min-height: 8px;
}

scrollbar slider:hover {
  background: rgba(255, 255, 255, 0.5);
}

performance considerations

minimal overhead

scrollbar rendering has negligible performance impact:

efficient updates: only redraws when scrollback changes
gtk native: uses hardware-accelerated gtk rendering
no blocking: scrollbar state doesn’t block renderer (fixed in commit be608ea2d)
memory: adds ~100kb per terminal for scrollbar metadata

disable for extreme performance

if every cycle counts:

scrollbar = never
background-blur = 0
background-opacity = 1.0

you retain all scrolling functionality via mouse wheel and keyboard.

troubleshooting

scrollbar not appearing

verify feature availability

# check build date
ls -l $(which ghostty)

# ensure it's from main branch
ghostty --version

if using stable 1.2.0, scrollbars are not available.

check configuration

# verify config syntax
ghostty validate-config ~/.config/ghostty/config

# check current scrollbar setting
grep scrollbar ~/.config/ghostty/config

rebuild from main

cd ~/src/ghostty
git checkout main
git pull origin main
git log --oneline | grep -i scrollbar  # should show PR #9245 commits

zig build -Doptimize=ReleaseFast
sudo zig build -Doptimize=ReleaseFast --prefix /usr/local install

scrollbar not visible with system setting

your desktop environment may use overlay scrollbars (appear only on hover):

# check overlay scrolling setting
gsettings get org.gnome.desktop.interface overlay-scrolling

# try disabling overlay for always-visible scrollbars
gsettings set org.gnome.desktop.interface overlay-scrolling false

scrollbar styling issues

reset gtk theme cache:

# clear gtk cache
rm -rf ~/.cache/gtk-3.0
rm -rf ~/.cache/gtk-4.0

# restart ghostty

scrollbar causes crashes or hangs

if experiencing instability:

# check for the renderer fix
cd ~/src/ghostty
git log --oneline | grep "scrollbar state to block"

# should show: be608ea2d renderer: don't allow the scrollbar state to block the renderer

if missing, update and rebuild:

git pull origin main
zig build -Doptimize=ReleaseFast
sudo zig build -Doptimize=ReleaseFast --prefix /usr/local install

reporting bugs

since this is experimental, report issues:

verify main branch: git log --oneline | head -5
note commit: include commit hash from git rev-parse HEAD
include config: sanitize and include relevant config
describe behavior: expected vs actual
report: github issues

if scrollbars don’t fit your workflow:

mouse wheel

smooth scrolling without visual scrollbar:

scrollbar = never

mouse wheel scrolling still works perfectly.

efficient keyboard-driven scrolling:

# shell integration enables prompt jumping
shell-integration = detect
shell-integration-features = cursor,sudo,title

# jump between prompts
keybind = ctrl+shift+up=jump_to_prompt:-1
keybind = ctrl+shift+down=jump_to_prompt:1

# page up/down work by default

find specific content:

keybind = ctrl+shift+f=search

search and jump directly to matches.

technical details

implementation

the scrollbar implementation consists of several key components:

core metadata: PageList.Scrollbar struct tracks total, offset, and len for scrollback position (commit e1b527fb9)
renderer events: emits scrollbar apprt events when scrollback changes (commit da7736cd4)
gtk widget: SurfaceScrolledWindow wraps terminal surface in GtkScrolledWindow
policy mapping: closureScrollbarPolicy function maps config enum (never → .never, system → .automatic) to gtk policy types
adjustment sync: setScrollbar updates gtk adjustment with scrollback values
ui template: blueprint file binds scrollbar policy to config, with horizontal scrollbar always disabled

files involved

key implementation files with line references:

src/apprt/gtk/class/surface_scrolled_window.zig: main scrollbar widget wrapper (209 lines added)
src/apprt/gtk/ui/1.5/surface-scrolled-window.blp: gtk blueprint defining scrollbar ui (11 lines)
src/apprt/gtk/class/surface.zig: setScrollbar() method and adjustment handling (229 lines added)
src/config/Config.zig:1217-1233: scrollbar configuration (⚠️ line 1232 comment is outdated, still claims “GTK doesn’t yet support scrollbars”)
src/terminal/PageList.zig:2188-2198: Scrollbar struct with total, offset, len fields

commit history

scrollbar development timeline from git log:

oct 15, 2025 19:42: e1b527fb9 - core: PageList tracks minimum metadata for rendering a scrollbar (#9225)
oct 15, 2025 21:03: da7736cd4 - renderer: emit scrollbar apprt event when scrollback changes
oct 16, 2025 09:18: 2937aff51 - gtk: mark scrollbar as unimplemented
oct 16, 2025 09:49: 4b34b2389 - config: add scrollbar config to control when scrollbars appear
oct 16, 2025 14:09: 0e0bbfaa6 - macOS: Scrollbars (#9232)
oct 16, 2025 15:49: ed443bc6e - gtk: Scrollbars (implementation commit, +467 lines)
oct 17, 2025 09:21: 063070915 - gtk: Scrollbars (#9245) - merge to main, fixes #111
oct 17, 2025 19:48: 5b7f14564 - macos: make terminal smaller to account for legacy scrollbar
oct 17, 2025 20:18: 5bf05dfe3 - macos: make terminal smaller to account for legacy scrollbar (#9255)
oct 18, 2025 21:28: 3a9eedcd1 - renderer: don’t allow the scrollbar state to block the renderer
oct 18, 2025 21:34: be608ea2d - renderer: don’t allow the scrollbar state to block the renderer (#9270) - critical bug fix

comparison: macos vs linux

similarities

both platforms now support scrollbars:

same scrollbar config option
similar visual appearance
equivalent functionality
theme integration

differences

aspect	macos	linux (gtk)
api	native cocoa scrollview	gtk scrolledwindow
overlay	system preference	gtk overlay-scrolling
theming	macos accent colors	gtk theme
merged	oct 16, 2025 (pr #9232)	oct 17, 2025 (pr #9245)

both implementations close issue #111, bringing feature parity across platforms.

future development

potential enhancements

likely future improvements:

horizontal scrollbar: for wide content (currently hardcoded to never in blueprint)
custom scrollbar width: configuration option for width/thickness
autohide timing: configurable delay for overlay mode
scroll indicators: minimal markers instead of full scrollbar
touch gestures: better touchscreen/touchpad support
update config docs: fix outdated comment claiming GTK doesn’t support scrollbars

stable release

scrollbar support will likely appear in:

target: next release after 1.2.0 (possibly 1.3.0)
timeline: when stabilization complete (weeks/months)
status: monitor milestone tracking

complete your ghostty setup:

ghostty configuration guide: comprehensive config reference
ubuntu build guide: building from source
default terminal setup: system integration

recommended complementary settings:

# scrollbar configuration
scrollbar = system

# enhance scrollback navigation
scrollback-limit = 100000000  # 100mb history
shell-integration = detect
shell-integration-features = cursor,sudo,title

# prompt jumping keybinds
keybind = ctrl+shift+up=jump_to_prompt:-1
keybind = ctrl+shift+down=jump_to_prompt:1

# visual polish
background-opacity = 0.95
background-blur = 10
theme = "light:Catppuccin Latte,dark:Catppuccin Mocha"

resources

next steps

build from main following the build guide
verify scrollbar support by checking commit history
configure scrollbars by adding scrollbar = system to config
customize gtk theme for desired scrollbar appearance
test integration with your desktop environment settings
report bugs if experiencing issues with this experimental feature
monitor updates for stabilization and eventual stable release