Configuration Options
This is the complete runtime option reference for plugin:hyprexpo:* settings. Use the short key names inside a plugin { hyprexpo { ... } } block, or use the fully qualified names when setting options elsewhere in Hyprland config.
Hyprland 0.55 deprecated the custom keyword API that older HyprExpo configs used. HyprExpo no longer registers hyprexpo_gesture or hyprexpo_workspace_method. Use plugin:hyprexpo:workspace_method for workspace placement and the Lua API for gestures.
Example Shape
plugin {
hyprexpo {
columns = 3
gaps_in = 5
gaps_out = 0
bg_col = rgb(111111)
workspace_method = center current
keynav_enable = 1
label_enable = 1
border_width = 2
}
}In hyprland.lua, use hl.config() with a nested plugin.hyprexpo table:
hl.config({
plugin = {
hyprexpo = {
columns = 3,
gaps_in = 5,
gaps_out = 0,
bg_col = "rgb(111111)",
workspace_method = "center current",
keynav_enable = 1,
label_enable = 1,
border_width = 2,
},
},
})hl.plugin.hyprexpo is the Lua helper namespace for dispatchers and gestures; it is not the configuration block.
PR #605 Compatibility Keys
These keys are registered for the active-overview port and are intentionally separate from the richer sandwichfarm config surface. They are kept for later integration and should not replace the newer keys below.
| key | type | legacy meaning | newer sandwichfarm counterpart |
|---|---|---|---|
plugin:hyprexpo:dynamic_grid | int | opt-in dynamic workspace enumeration (default: off) | no direct equivalent yet |
plugin:hyprexpo:fill_gaps | int | expand min..max workspace IDs when dynamic | no direct equivalent yet |
plugin:hyprexpo:mru_sort | int | put the current workspace first | no direct equivalent yet |
plugin:hyprexpo:active_highlight_col | color | active tile highlight color | border_color_current |
plugin:hyprexpo:active_highlight_border | int | active tile highlight width | border_width |
plugin:hyprexpo:hover_highlight_col | color | hovered tile highlight color | border_color_hover |
plugin:hyprexpo:hover_highlight_border | int | hovered tile highlight width | border_width |
plugin:hyprexpo:label_pos | string | legacy underscore anchor such as top_right | label_position (top-right) |
plugin:hyprexpo:label_size | int | legacy badge size; text renders at roughly half this size | label_font_size |
plugin:hyprexpo:label_col | color | legacy label tint | label_color / label_color_default |
plugin:hyprexpo:show_workspace_names | int | legacy name/number toggle | show_workspace_numbers and label_text_mode |
plugin:hyprexpo:enable_keyboard_nav | int | legacy keyboard-navigation toggle | keynav_enable |
plugin:hyprexpo:enable_drag_move | int | legacy drag-move toggle | no direct equivalent yet |
plugin:hyprexpo:animate_entry | int | legacy open animation toggle | no direct equivalent yet |
plugin:hyprexpo:wallpaper_bg | int | draw the monitor wallpaper behind the overview tiles | optional active-overview extension |
Enable the active-workspace layout explicitly; all compatibility options default to the existing fixed-grid behavior:
plugin {
hyprexpo {
dynamic_grid = 1
fill_gaps = 0
mru_sort = 0
show_workspace_names = 1
label_pos = top_right
label_size = 48
wallpaper_bg = 1
}
}Layout and Behavior
Background Image
The following options draw a custom image behind the entire overview in both grid and native scrolling sessions. They do not change workspace thumbnails.
plugin {
hyprexpo {
bg_image = ~/Pictures/wallpaper.jpg
bg_image_fit = cover
bg_image_blur = 8
}
}In hyprland.lua:
hl.config({
plugin = {
hyprexpo = {
bg_image = "~/Pictures/wallpaper.jpg",
bg_image_fit = "cover",
bg_image_blur = 8,
},
},
})bg_image: image file path; default empty (disabled). Absolute paths and~/paths are supported. Formats are provided by the installed Hyprgraphics image loaders, including PNG, JPEG, and WebP where available.bg_image_fit:cover(default) fills the monitor while preserving aspect ratio and cropping centrally;containshows the whole image with the existing solid background visible in unused space;stretchfills without preserving aspect ratio. Unknown values fall back tocoverat runtime.bg_image_blur: integer blur radius in output pixels,0..64, default0. Three box-filter passes approximate Gaussian blur. Only the image is blurred; windows, labels, and borders stay sharp.
Each monitor fits the image independently. Up to four fitted, blurred textures are cached across overview sessions; loading and filtering do not run on every frame or when reopening a cached background. On a cache miss, image decoding, fitting, and blur run synchronously and can briefly pause compositor rendering. As a reference, blur alone at radius 8 took about 0.06 seconds at 1080p and 0.27 seconds at 4K in an optimized build on the review machine; decoding and upload add to that cost. Larger images and slower machines can take longer. Default plugin builds are optimized; use an explicit CMake Debug configuration or override Make's CXXFLAGS when an unoptimized build is needed. Reload the Hyprland configuration to apply changes, including replacement of the image at the same path. A monitor resolution change also rebuilds the texture.
A custom image takes precedence over wallpaper_bg in the grid. Empty or unreadable paths retain the existing background: the grid uses bg_col and, when enabled and available, wallpaper_bg; scrolling retains its solid color. Image loading errors are reported in the compositor log.
General options
| key | type | description | default |
|---|---|---|---|
plugin:hyprexpo:columns | int | desktops per row, clamped to 1..7 | 3 |
plugin:hyprexpo:rows | int | fixed-grid rows, positive values clamped to 1..7; 0 or negative values follow columns | 0 |
plugin:hyprexpo:gaps_in | int | spacing between tiles in pixels | 5 |
plugin:hyprexpo:gaps_out | int | outer margin around the grid in pixels | 0 |
plugin:hyprexpo:bg_col | color | grid background color | 0xFF111111 |
plugin:hyprexpo:workspace_method | string | placement: center current or first <workspace> | center current |
plugin:hyprexpo:overview_mode | string | auto detects Hyprland's native scrolling layout on the triggering workspace and opens the scrolling overview for it; grid always opens the classic workspace grid regardless of detected layout. Unrecognized values behave as auto | auto |
plugin:hyprexpo:skip_empty | bool int | skip empty workspaces using selector m when enabled | 0 |
plugin:hyprexpo:max_workspace | int | when skip_empty = 0, cap sequential overview tiles at this workspace ID; 0 keeps Hyprland selector behavior | 0 |
plugin:hyprexpo:gesture_distance | int | swipe distance considered complete | 200 |
plugin:hyprexpo:gesture_fingers | int | fingers for the interactive swipe gesture; 0 disables, otherwise 2-9 | 0 |
plugin:hyprexpo:gesture_direction | string | swipe direction: up, down, left, right, vertical, horizontal, pinch | up |
plugin:hyprexpo:cancel_key | string | comma-separated key names that close overview without selecting; none or off disables | escape |
plugin:hyprexpo:show_cursor | bool int | keep the cursor visible while overview is open; set 0 for old hidden-cursor behavior | 1 |
plugin:hyprexpo:show_pinned_windows | bool int | render pinned/PiP windows in workspace preview thumbnails; default 0 hides them from previews only | 0 |
plugin:hyprexpo:cross_monitor | bool int | include foreign workspaces in fixed first grids; see below | 0 |
plugin:hyprexpo:scrolling_thumbnail_budget | int | scrolling thumbnail budget multiplier m, clamped to 1..16; total capture pixels are bounded by m * W * H for monitor size W x H | 4 |
plugin:hyprexpo:scrolling_input_debug | bool int | enable deterministic input and loaded native mutation acceptance dispatchers; leave disabled outside disposable testing | 0 |
Cross-monitor workspace grid
cross_monitor = 1 makes a fixed workspace_method = first 1 grid include consecutive absolute workspace IDs, including those owned by other monitors. It defaults to 0, which keeps the existing monitor-local ordering. Use skip_empty = 0, dynamic_grid = 0, and a positive first workspace ID; other workspace methods keep their existing behavior. max_workspace still caps the emitted IDs. For scrolling layouts, set overview_mode = grid.
Foreign tiles are captured on their owning monitor and refresh when that monitor reports damage. Updates are coalesced until the overview monitor renders; idle foreign monitors do not start a polling loop. Hidden applications may pause or be throttled; previews use available content without forcing frame callbacks for hidden clients. Selecting one closes all overviews immediately, without zooming that tile across the overview monitor, then focuses its workspace and moves the cursor to that monitor. Workspace ownership stays unchanged. Window dragging and index-based window moves are disabled in cross-monitor grids. Existing per-monitor grids retain dragging.
Rectangular fixed grids
Set positive rows to choose the height independently of columns. For example, this makes a five-column, two-row grid with ten slots:
hl.config({plugin = {hyprexpo = {
columns = 5,
rows = 2,
dynamic_grid = 0,
skip_empty = 0,
}}})Workspace previews retain their aspect ratio and the grid is centered with letterboxing as needed. Empty and not-yet-created workspaces remain available as selection and drag/drop targets. A workspace cap may leave non-selectable padding inside the configured rectangle; it does not shrink the grid.
The default rows = 0 inherits the column count, preserving existing square-grid behavior. It does not derive rows from workspace count. rows has no effect on dynamic_grid = 1 or native scrolling-layout overviews. The existing first-anchor growth can increase columns when uncapped, but explicit rows stay fixed.
Pinned windows, including browser Picture-in-Picture windows, stay pinned and visible in normal Hyprland. By default HyprExpo hides them only while capturing workspace preview thumbnails so they do not appear on every tile. Set show_pinned_windows = 1 to opt in to the old preview behavior.
The scrolling budget is shared across every tight target thumbnail in the active overview. A per-target cap is applied first; if the requested total still exceeds m * W * H, every target is scaled by the same square-root factor, with a 16-pixel minimum fallback. This bounds GPU memory without dropping offscreen columns from the overview. See Scrolling Overview.
Trackpad gesture
gesture_fingers and gesture_direction register the interactive, follow-your-finger expo gesture from plain config. They remain expo-only; registering the cancel action requires hl.plugin.hyprexpo.gesture{} in a Lua config. Hyprland selects either hyprlang or Lua for the whole config and a .lua cannot be sourced from a .conf, so hyprlang users need these keys to reach the expo gesture at all.
plugin {
hyprexpo {
gesture_fingers = 3
gesture_direction = vertical
}
}gesture_fingers = 0 (the default) registers nothing, leaving trackpad handling entirely to Hyprland and Lua. Use a gesture_direction that does not collide with an existing Hyprland gesture = binding for the same finger count.
Bad values are rejected when the gesture is registered, not while the config is parsed. An unknown gesture_direction, or a gesture_fingers value that is neither 0 nor in 2-9, raises a notification and leaves the gesture unregistered rather than failing silently. Under the hyprlang backend these do not reach hyprctl configerrors: plugins have no API for adding entries there, and hyprlang does not run the validators attached to plugin config values.
Tile Appearance
| key | type | description | default |
|---|---|---|---|
plugin:hyprexpo:tile_rounding | int | corner radius in pixels for workspace previews | 0 |
plugin:hyprexpo:tile_rounding_power | float | rounding curve exponent | 2.0 |
plugin:hyprexpo:tile_rounding_focus | int | focused tile radius; -1 inherits tile_rounding | -1 |
plugin:hyprexpo:tile_rounding_current | int | current tile radius; -1 inherits tile_rounding | -1 |
plugin:hyprexpo:tile_rounding_hover | int | hovered tile radius; -1 inherits tile_rounding | -1 |
plugin:hyprexpo:border_width | int | border thickness in pixels | 2 |
plugin:hyprexpo:border_color | string | default border for non-highlighted tiles; solid color or gradient | empty |
plugin:hyprexpo:border_color_current | string | current workspace tile border; solid color or gradient | rgb(66ccff) |
plugin:hyprexpo:border_color_focus | string | keyboard-focused tile border; solid color or gradient | rgb(ffcc66) |
plugin:hyprexpo:border_color_hover | string | pointer-hovered tile border; solid color or gradient | rgb(aabbcc) |
plugin:hyprexpo:border_grad_current | string | deprecated current-tile gradient fallback; use border_color_current | empty |
plugin:hyprexpo:border_grad_focus | string | deprecated focused-tile gradient fallback; use border_color_focus | empty |
plugin:hyprexpo:border_grad_hover | string | deprecated hovered-tile gradient fallback; use border_color_hover | empty |
plugin:hyprexpo:border_style | string | deprecated compatibility key; border style is detected from the color format | simple |
Drag-Drop Window Styling
These options style the visual feedback shown while dragging a window between workspace previews. HyprExpo renders the under-pointer drag proxy and, while the pointer is over a valid target workspace, a positional landing proxy inside that target tile. Empty border color values inherit the focused tile border, so the default look stays unchanged until you opt into drag/drop-specific styling.
The landing proxy is visual-only in this milestone. It previews drop intent; the actual release still uses the existing safe workspace move behavior.
| key | type | description | default |
|---|---|---|---|
plugin:hyprexpo:drag_drop_proxy_color | color | translucent dragged-window proxy before the move threshold is crossed | 0x24EDB342 |
plugin:hyprexpo:drag_drop_proxy_active_color | color | dragged-window proxy after movement is active | 0x3DEDB342 |
plugin:hyprexpo:drag_drop_proxy_border_color | string | proxy border; accepts solid colors or gradients, empty inherits border_color_focus / border_grad_focus | empty |
plugin:hyprexpo:drag_drop_proxy_border_width | int | proxy border width; -1 inherits max(2, border_width + 1), 0 disables | -1 |
plugin:hyprexpo:drag_drop_proxy_rounding | int | proxy corner radius in pixels; -1 inherits the automatic focused-tile rounding | -1 |
plugin:hyprexpo:drag_drop_source_border_color | string | source workspace border while a drag/drop move is active; accepts solid colors or gradients, empty inherits focus border | empty |
plugin:hyprexpo:drag_drop_source_border_width | int | source workspace border width while dragging; -1 inherits border_width, 0 disables | -1 |
Color Values
Color-backed settings such as bg_col, label_color*, label_bg_color, and selection_label_color use Hyprland color parsing. Solid border colors are strings because border settings also accept gradient specs.
Solid values:
bg_col = rgb(111111)
border_color_current = rgb(66ccff)Gradient values:
border_color_current = rgba(33ccffee) rgba(00ff99ee) 45degDrag/drop styling values:
drag_drop_proxy_color = rgba(66ccff22)
drag_drop_proxy_active_color = rgba(66ccff44)
drag_drop_proxy_border_color = rgba(66ccffee) rgba(ffcc66ee) 45deg
drag_drop_source_border_color = rgb(ffcc66)
drag_drop_proxy_border_width = 3
drag_drop_proxy_rounding = 10Workspace Labels
| key | type | description | default |
|---|---|---|---|
plugin:hyprexpo:label_enable | bool int | enable workspace labels | 1 |
plugin:hyprexpo:label_color | color | legacy accepted label color; state-specific colors below control rendering | 0xFFFFFFFF |
plugin:hyprexpo:label_text_mode | string | label text source: token, index, or id | token |
plugin:hyprexpo:label_token_map | string | comma-separated tokens by visible tile order; empty entries skip | empty |
plugin:hyprexpo:label_position | string | label anchor: top-left, top-right, bottom-left, bottom-right, or center | center |
plugin:hyprexpo:label_offset_x | int | horizontal offset from the label anchor in pixels | 0 |
plugin:hyprexpo:label_offset_y | int | vertical offset from the label anchor in pixels | 0 |
plugin:hyprexpo:label_show | string | visibility rule: always, hover, focus, hover+focus, current+focus, or never | always |
plugin:hyprexpo:label_color_default | color | default label text color | rgb(ffffff) |
plugin:hyprexpo:label_color_hover | color | hovered label text color | rgb(eeeeee) |
plugin:hyprexpo:label_color_focus | color | keyboard-focused label text color | rgb(ffcc66) |
plugin:hyprexpo:label_color_current | color | current workspace label text color | rgb(66ccff) |
plugin:hyprexpo:show_workspace_numbers | bool int | force labels to show workspace IDs regardless of label_text_mode | 0 |
plugin:hyprexpo:workspace_number_color | color | forced workspace ID label color | rgb(ffffff) |
plugin:hyprexpo:label_scale_hover | float | hover scale multiplier for labels | 1.0 |
plugin:hyprexpo:label_scale_focus | float | keyboard-focus scale multiplier for labels | 1.0 |
plugin:hyprexpo:label_font_size | int | base label font size in pixels | 16 |
plugin:hyprexpo:label_font_family | string | Pango font family | sans |
plugin:hyprexpo:label_font_bold | bool int | render label text in bold | 0 |
plugin:hyprexpo:label_font_italic | bool int | render label text in italic | 0 |
plugin:hyprexpo:label_text_underline | bool int | underline label text | 0 |
plugin:hyprexpo:label_text_strikethrough | bool int | strikethrough label text | 0 |
plugin:hyprexpo:label_pixel_snap | bool int | snap label positions to whole pixels | 1 |
plugin:hyprexpo:label_center_adjust_x | int | manual center nudge in pixels for centered labels | 0 |
plugin:hyprexpo:label_center_adjust_y | int | manual center nudge in pixels for centered labels | 0 |
plugin:hyprexpo:label_bg_enable | bool int | draw a background bubble behind labels | 1 |
plugin:hyprexpo:label_bg_color | color | label background color | rgba(00000088) |
plugin:hyprexpo:label_bg_shape | string | label background shape: circle, square, or rounded | circle |
plugin:hyprexpo:label_bg_rounding | int | radius for rounded label backgrounds | 8 |
plugin:hyprexpo:label_padding | int | background padding around label text in pixels | 8 |
Label token maps are comma-separated and follow visible tile order:
label_text_mode = token
label_token_map = 1,2,3,4,5,6,7,8,9,0Selection Labels
Selection labels are optional overlays used by hyprexpo:kb_select. They let normal workspace labels stay stable while selection tokens use a separate map.
| key | type | description | default |
|---|---|---|---|
plugin:hyprexpo:selection_label_enable | bool int | enable the separate selection-token overlay | 0 |
plugin:hyprexpo:selection_label_token_map | string | comma-separated tokens by visible tile order; empty entries skip | a,s,d,f,g,q,w,e,r,t,z,x,c,v,b |
plugin:hyprexpo:selection_label_position | string | selection label anchor: top-left, top-right, bottom-left, bottom-right, or center | top-right |
plugin:hyprexpo:selection_label_offset_x | int | horizontal offset from the selection-label anchor in pixels | 6 |
plugin:hyprexpo:selection_label_offset_y | int | vertical offset from the selection-label anchor in pixels | 6 |
plugin:hyprexpo:selection_label_color | color | selection-token text color | rgb(ffcc66) |
Example token-based selection:
selection_label_enable = 1
selection_label_token_map = a,s,d,f,g,q,w,e,r,tThen bind hyprexpo:kb_select to those tokens in the overview submap.
Keyboard Navigation
| key | type | description | default |
|---|---|---|---|
plugin:hyprexpo:keynav_enable | bool int | enable keyboard navigation and the overview submap behavior | 1 |
plugin:hyprexpo:number_key_mode | string | raw digit handling: workspace, index, or passthrough for user mappings | workspace |
plugin:hyprexpo:keynav_wrap_h | bool int | wrap horizontally at row edges | 1 |
plugin:hyprexpo:keynav_wrap_v | bool int | wrap vertically at column edges | 1 |
plugin:hyprexpo:keynav_reading_order | bool int | use row-major horizontal movement instead of spatial movement | 0 |
Related References
- Labels and borders shows focused examples for appearance tuning.
- Keyboard navigation shows the matching submap binds.
- Lua gestures documents
hl.plugin.hyprexpo.gesture. - Dispatchers documents
hyprexpo:*dispatchers.
Safe Failure Behavior
Invalid columns, rows, workspace methods, label tokens, border colors, drag/drop border colors, gradient values, and bool-int options are expected to fail safely. The plugin should log invalid values or use a fallback instead of crashing Hyprland during render.