hyprland-wiki/pages/Configuring/Variables.md
2024-08-06 13:42:36 +02:00

31 KiB

weight title
2 Variables

For basic syntax info, see Configuring Hyprland.

This page documents all the "options" of Hyprland. For binds, monitors, animations, etc. see the sidebar. For anything else, see Keywords.

Please keep in mind some options that are layout-specific will be documented in the layout pages and not here. (See the Sidebar for Dwindle and Master layouts)

Variable types

type description
int integer
bool boolean, true or false (yes or no, on or off, 0 or 1) - any numerical value that is not 0 or 1 will cause undefined behavior.
float floating point number
color color (see hint below for color info)
vec2 vector with 2 float values, separated by a space (e.g. 0 0 or -10.9 99.1)
MOD a string modmask (e.g. SUPER or SUPERSHIFT or SUPER + SHIFT or SUPER and SHIFT or CTRL_SHIFT or empty for none. You are allowed to put any separators you please except for a ,)
str a string
gradient a gradient, in the form of color color ... [angle] where color is a color (see above) and angle is an angle in degrees, in the format of 123deg e.g. 45deg (e.g. rgba(11ee11ff) rgba(1111eeff) 45deg) Angle is optional and will default to 0deg

{{< callout type=info >}}

Colors:

You have 3 options:

rgba(), e.g. rgba(b3ff1aee)

rgb(), e.g. rgb(b3ff1a)

legacy, e.g. 0xeeb3ff1a -> ARGB order

{{< /callout >}}

{{< callout type=info >}}

Mod list:

SHIFT CAPS CTRL/CONTROL ALT MOD2 MOD3 SUPER/WIN/LOGO/MOD4 MOD5

{{< /callout >}}

Sections

General

name description type default
sensitivity mouse sensitivity (legacy, may cause bugs if not 1, prefer input:sensitivity) float 1.0
border_size size of the border around windows int 1
no_border_on_floating disable borders for floating windows bool false
gaps_in gaps between windows, also supports css style gaps (top, right, bottom, left -> 5,10,15,20) int 5
gaps_out gaps between windows and monitor edges, also supports css style gaps (top, right, bottom, left -> 5,10,15,20) int 20
gaps_workspaces gaps between workspaces. Stacks with gaps_out. int 0
col.inactive_border border color for inactive windows gradient 0xff444444
col.active_border border color for the active window gradient 0xffffffff
col.nogroup_border inactive border color for window that cannot be added to a group (see denywindowfromgroup dispatcher) gradient 0xffffaaff
col.nogroup_border_active active border color for window that cannot be added to a group gradient 0xffff00ff
layout which layout to use. [dwindle/master] str dwindle
no_focus_fallback if true, will not fall back to the next available window when moving focus in a direction where no window was found bool false
apply_sens_to_raw if on, will also apply the sensitivity to raw mouse output (e.g. sensitivity in games) NOTICE: really not recommended. bool false
resize_on_border enables resizing windows by clicking and dragging on borders and gaps bool false
extend_border_grab_area extends the area around the border where you can click and drag on, only used when general:resize_on_border is on. int 15
hover_icon_on_border show a cursor icon when hovering over borders, only used when general:resize_on_border is on. bool true
allow_tearing master switch for allowing tearing to occur. See the Tearing page. bool false
resize_corner force floating windows to use a specific corner when being resized (1-4 going clockwise from top left, 0 to disable) int 0

{{< callout type=warning >}}

Prefer using input:sensitivity over general:sensitivity to avoid bugs, especially with Wine/Proton apps.

{{< /callout >}}

Decoration

name description type default
rounding rounded corners' radius (in layout px) int 0
active_opacity opacity of active windows. [0.0 - 1.0] float 1.0
inactive_opacity opacity of inactive windows. [0.0 - 1.0] float 1.0
fullscreen_opacity opacity of fullscreen windows. [0.0 - 1.0] float 1.0
drop_shadow enable drop shadows on windows bool true
shadow_range Shadow range ("size") in layout px int 4
shadow_render_power in what power to render the falloff (more power, the faster the falloff) [1 - 4] int 3
shadow_ignore_window if true, the shadow will not be rendered behind the window itself, only around it. bool true
col.shadow shadow's color. Alpha dictates shadow's opacity. color 0xee1a1a1a
col.shadow_inactive inactive shadow color. (if not set, will fall back to col.shadow) color unset
shadow_offset shadow's rendering offset. vec2 [0, 0]
shadow_scale shadow's scale. [0.0 - 1.0] float 1.0
dim_inactive enables dimming of inactive windows bool false
dim_strength how much inactive windows should be dimmed [0.0 - 1.0] float 0.5
dim_special how much to dim the rest of the screen by when a special workspace is open. [0.0 - 1.0] float 0.2
dim_around how much the dimaround window rule should dim by. [0.0 - 1.0] float 0.4
screen_shader a path to a custom shader to be applied at the end of rendering. See examples/screenShader.frag for an example. str Empty

Blur

Subcategory decoration:blur:

name description type default
enabled enable kawase window background blur bool true
size blur size (distance) int 8
passes the amount of passes to perform int 1
ignore_opacity make the blur layer ignore the opacity of the window bool false
new_optimizations whether to enable further optimizations to the blur. Recommended to leave on, as it will massively improve performance. bool true
xray if enabled, floating windows will ignore tiled windows in their blur. Only available if blur_new_optimizations is true. Will reduce overhead on floating blur significantly. bool false
noise how much noise to apply. [0.0 - 1.0] float 0.0117
contrast contrast modulation for blur. [0.0 - 2.0] float 0.8916
brightness brightness modulation for blur. [0.0 - 2.0] float 0.8172
vibrancy Increase saturation of blurred colors. [0.0 - 1.0] float 0.1696
vibrancy_darkness How strong the effect of vibrancy is on dark areas . [0.0 - 1.0] float 0.0
special whether to blur behind the special workspace (note: expensive) bool false
popups whether to blur popups (e.g. right-click menus) bool false
popups_ignorealpha works like ignorealpha in layer rules. If pixel opacity is below set value, will not blur. [0.0 - 1.0] float 0.2

{{< callout type=important >}}

A subcategory is a nested category:

decoration {
    # ...
    # ...

    blur {
        # ...
        # ...
    }
}

Doing decoration:blur { is invalid!

{{< /callout >}}

{{< callout type=info >}}

blur:size and blur:passes have to be at least 1.

Increasing blur:passes is necessary to prevent blur looking wrong on higher blur:size values, but remember that higher blur:passes will require more strain on the GPU.

{{< /callout >}}

Animations

name description type default
enabled enable animations bool true
first_launch_animation enable first launch animation bool true

{{< callout type=info >}}

More about Animations.

{{< /callout >}}

Input

name description type default
kb_model Appropriate XKB keymap parameter. See the note below. str Empty
kb_layout Appropriate XKB keymap parameter str us
kb_variant Appropriate XKB keymap parameter str Empty
kb_options Appropriate XKB keymap parameter str Empty
kb_rules Appropriate XKB keymap parameter str Empty
kb_file If you prefer, you can use a path to your custom .xkb file. str Empty
numlock_by_default Engage numlock by default. bool false
resolve_binds_by_sym Determines how keybinds act when multiple layouts are used. If false, keybinds will always act as if the first specified layout is active. If true, keybinds specified by symbols are activated when you type the respective symbol with the current layout. bool false
repeat_rate The repeat rate for held-down keys, in repeats per second. int 25
repeat_delay Delay before a held-down key is repeated, in milliseconds. int 600
sensitivity Sets the mouse input sensitivity. Value is clamped to the range -1.0 to 1.0. libinput#pointer-acceleration float 0.0
accel_profile Sets the cursor acceleration profile. Can be one of adaptive, flat. Can also be custom, see below. Leave empty to use libinput's default mode for your input device. libinput#pointer-acceleration [adaptive/flat/custom] str Empty
force_no_accel Force no cursor acceleration. This bypasses most of your pointer settings to get as raw of a signal as possible. Enabling this is not recommended due to potential cursor desynchronization. bool false
left_handed Switches RMB and LMB bool false
scroll_points Sets the scroll acceleration profile, when accel_profile is set to custom. Has to be in the form <step> <points>. Leave empty to have a flat scroll curve. str Empty
scroll_method Sets the scroll method. Can be one of 2fg (2 fingers), edge, on_button_down, no_scroll. libinput#scrolling [2fg/edge/on_button_down/no_scroll] str Empty
scroll_button Sets the scroll button. Has to be an int, cannot be a string. Check wev if you have any doubts regarding the ID. 0 means default. int 0
scroll_button_lock If the scroll button lock is enabled, the button does not need to be held down. Pressing and releasing the button toggles the button lock, which logically holds the button down or releases it. While the button is logically held down, motion events are converted to scroll events. bool 0
scroll_factor Multiplier added to scroll movement for external mice. Note that there is a separate setting for touchpad scroll_factor. float 1.0
natural_scroll Inverts scrolling direction. When enabled, scrolling moves content directly, rather than manipulating a scrollbar. bool false
follow_mouse Specify if and how cursor movement should affect window focus. See the note below. [0/1/2/3] int 1
mouse_refocus If disabled, mouse focus won't switch to the hovered window unless the mouse crosses a window boundary when follow_mouse=1. bool true
float_switch_override_focus If enabled (1 or 2), focus will change to the window under the cursor when changing from tiled-to-floating and vice versa. If 2, focus will also follow mouse on float-to-float switches. int 1
special_fallthrough if enabled, having only floating windows in the special workspace will not block focusing windows in the regular workspace. bool false
off_window_axis_events Handles axis events around (gaps/border for tiled, dragarea/border for floated) a focused window. 0 ignores axis events 1 sends out-of-bound coordinates 2 fakes pointer coordinates to the closest point inside the window 3 warps the cursor to the closest point inside the window int 1
emulate_discrete_scroll Emulates discrete scrolling from high resolution scrolling events. 0 disables it, 1 enables handling of non-standard events only, and 2 force enables all scroll wheel events to be handled int 1

{{< callout type=info >}}

XKB Settings

You can find a list of models, layouts, variants and options in /usr/share/X11/xkb/rules/base.lst. Alternatively, you can use the localectl command to discover what is available on your system.

For switchable keyboard configurations, take a look at the uncommon tips & tricks page entry.

{{< /callout >}}

{{< callout type=info >}}

Follow Mouse Cursor

  • 0 - Cursor movement will not change focus.
  • 1 - Cursor movement will always change focus to the window under the cursor.
  • 2 - Cursor focus will be detached from keyboard focus. Clicking on a window will move keyboard focus to that window.
  • 3 - Cursor focus will be completely separate from keyboard focus. Clicking on a window will not change keyboard focus.

Custom accel profiles

accel_profile

custom <step> <points...>

Example: custom 200 0.0 0.5

scroll_points

NOTE: Only works when accel_profile is set to custom.

<step> <points...>

Example: 0.2 0.0 0.5 1 1.2 1.5

To mimic the Windows acceleration curves, take a look at this script.

See the libinput doc for more insights on how it works.

{{< /callout >}}

Touchpad

Subcategory input:touchpad:

name description type default
disable_while_typing Disable the touchpad while typing. bool true
natural_scroll Inverts scrolling direction. When enabled, scrolling moves content directly, rather than manipulating a scrollbar. bool false
scroll_factor Multiplier applied to the amount of scroll movement. float 1.0
middle_button_emulation Sending LMB and RMB simultaneously will be interpreted as a middle click. This disables any touchpad area that would normally send a middle click based on location. libinput#middle-button-emulation bool false
tap_button_map Sets the tap button mapping for touchpad button emulation. Can be one of lrm (default) or lmr (Left, Middle, Right Buttons). [lrm/lmr] str Empty
clickfinger_behavior Button presses with 1, 2, or 3 fingers will be mapped to LMB, RMB, and MMB respectively. This disables interpretation of clicks based on location on the touchpad. libinput#clickfinger-behavior bool false
tap-to-click Tapping on the touchpad with 1, 2, or 3 fingers will send LMB, RMB, and MMB respectively. bool true
drag_lock When enabled, lifting the finger off for a short time while dragging will not drop the dragged item. libinput#tap-and-drag bool false
tap-and-drag Sets the tap and drag mode for the touchpad bool false

Touchdevice

Subcategory input:touchdevice:

name description type default
transform Transform the input from touchdevices. The possible transformations are the same as those of the monitors int 0
output The monitor to bind touch devices. The default is auto-detection. To stop auto-detection, use an empty string or the "Empty" value. string Auto
enabled Whether input is enabled for touch devices. bool true

Tablet

Subcategory input:tablet:

name description type default
transform transform the input from tablets. The possible transformations are the same as those of the monitors int 0
output the monitor to bind tablets. Empty means unbound. string Empty
region_position position of the mapped region in monitor layout. vec2 [0, 0]
region_size size of the mapped region. When this variable is set, tablet input will be mapped to the region. [0, 0] or invalid size means unset. vec2 [0, 0]
relative_input whether the input should be relative bool false
left_handed if enabled, the tablet will be rotated 180 degrees bool false
active_area_size size of tablet's active area in mm vec2 [0, 0]
active_area_position position of the active area in mm vec2 [0, 0]

Per-device input config

Described here.

Gestures

name description type default
workspace_swipe enable workspace swipe gesture on touchpad bool false
workspace_swipe_fingers how many fingers for the touchpad gesture int 3
workspace_swipe_min_fingers if enabled, workspace_swipe_fingers is considered the minimum number of fingers to swipe bool false
workspace_swipe_distance in px, the distance of the touchpad gesture int 300
workspace_swipe_touch enable workspace swiping from the edge of a touchscreen bool false
workspace_swipe_invert invert the direction (touchpad only) bool true
workspace_swipe_touch_invert invert the direction (touchscreen only) bool false
workspace_swipe_min_speed_to_force minimum speed in px per timepoint to force the change ignoring cancel_ratio. Setting to 0 will disable this mechanic. int 30
workspace_swipe_cancel_ratio how much the swipe has to proceed in order to commence it. (0.7 -> if > 0.7 * distance, switch, if less, revert) [0.0 - 1.0] float 0.5
workspace_swipe_create_new whether a swipe right on the last workspace should create a new one. bool true
workspace_swipe_direction_lock if enabled, switching direction will be locked when you swipe past the direction_lock_threshold (touchpad only). bool true
workspace_swipe_direction_lock_threshold in px, the distance to swipe before direction lock activates (touchpad only). int 10
workspace_swipe_forever if enabled, swiping will not clamp at the neighboring workspaces but continue to the further ones. bool false
workspace_swipe_use_r if enabled, swiping will use the r prefix instead of the m prefix for finding workspaces. bool false

Group

name description type default
insert_after_current whether new windows in a group spawn after current or at group tail bool true
focus_removed_window whether Hyprland should focus on the window that has just been moved out of the group bool true
col.border_active active group border color gradient 0x66ffff00
col.border_inactive inactive (out of focus) group border color gradient 0x66777700
col.border_locked_active active locked group border color gradient 0x66ff5500
col.border_locked_inactive inactive locked group border color gradient 0x66775500

Groupbar

Subcategory group:groupbar:

name description type default
enabled enables groupbars bool true
font_family font used to display groupbar titles, use misc:font_family if not specified string Empty
font_size font size of groupbar title int 8
gradients enables gradients bool true
height height of the groupbar int 14
stacked render the groupbar as a vertical stack bool false
priority sets the decoration priority for groupbars int 3
render_titles whether to render titles in the group bar decoration bool true
scrolling whether scrolling in the groupbar changes group active window bool true
text_color controls the group bar text color color 0xffffffff
col.active active group border color gradient 0x66ffff00
col.inactive inactive (out of focus) group border color gradient 0x66777700
col.locked_active active locked group border color gradient 0x66ff5500
col.locked_inactive inactive locked group border color gradient 0x66775500

Misc

name description type default
disable_hyprland_logo disables the random Hyprland logo / anime girl background. :( bool false
disable_splash_rendering disables the Hyprland splash rendering. (requires a monitor reload to take effect) bool false
col.splash Changes the color of the splash text (requires a monitor reload to take effect). color 0xffffffff
font_family Set the global default font to render the text including debug fps/notification, config error messages and etc., selected from system fonts. string Sans
splash_font_family Changes the font used to render the splash text, selected from system fonts (requires a monitor reload to take effect). string Empty
force_default_wallpaper Enforce any of the 3 default wallpapers. Setting this to 0 or 1 disables the anime background. -1 means "random". [-1/0/1/2] int -1
vfr controls the VFR status of Hyprland. Heavily recommended to leave enabled to conserve resources. bool true
vrr controls the VRR (Adaptive Sync) of your monitors. 0 - off, 1 - on, 2 - fullscreen only [0/1/2] int 0
mouse_move_enables_dpms If DPMS is set to off, wake up the monitors if the mouse moves. bool false
key_press_enables_dpms If DPMS is set to off, wake up the monitors if a key is pressed. bool false
always_follow_on_dnd Will make mouse focus follow the mouse when drag and dropping. Recommended to leave it enabled, especially for people using focus follows mouse at 0. bool true
layers_hog_keyboard_focus If true, will make keyboard-interactive layers keep their focus on mouse move (e.g. wofi, bemenu) bool true
animate_manual_resizes If true, will animate manual window resizes/moves bool false
animate_mouse_windowdragging If true, will animate windows being dragged by mouse, note that this can cause weird behavior on some curves bool false
disable_autoreload If true, the config will not reload automatically on save, and instead needs to be reloaded with hyprctl reload. Might save on battery. bool false
enable_swallow Enable window swallowing bool false
swallow_regex The class regex to be used for windows that should be swallowed (usually, a terminal). To know more about the list of regex which can be used use this cheatsheet. str Empty
swallow_exception_regex The title regex to be used for windows that should not be swallowed by the windows specified in swallow_regex (e.g. wev). The regex is matched against the parent (e.g. Kitty) window's title on the assumption that it changes to whatever process it's running. str Empty
focus_on_activate Whether Hyprland should focus an app that requests to be focused (an activate request) bool false
mouse_move_focuses_monitor Whether mouse moving into a different monitor should focus it bool true
render_ahead_of_time [Warning: buggy] starts rendering before your monitor displays a frame in order to lower latency bool false
render_ahead_safezone how many ms of safezone to add to rendering ahead of time. Recommended 1-2. int 1
allow_session_lock_restore if true, will allow you to restart a lockscreen app in case it crashes (red screen of death) bool false
background_color change the background color. (requires enabled disable_hyprland_logo) color 0x111111
close_special_on_empty close the special workspace if the last window is removed bool true
new_window_takes_over_fullscreen if there is a fullscreen window, whether a new tiled window opened should replace the fullscreen one or stay behind. 0 - behind, 1 - takes over, 2 - unfullscreen the current fullscreen window [0/1/2] int 0
exit_window_retains_fullscreen if true, closing a fullscreen window makes the next focused window fullscreen bool false
initial_workspace_tracking if enabled, windows will open on the workspace they were invoked on. 0 - disabled, 1 - single-shot, 2 - persistent (all children too) int 1
middle_click_paste whether to enable middle-click-paste (aka primary selection) bool true

Binds

name description type default
pass_mouse_when_bound if disabled, will not pass the mouse events to apps / dragging windows around if a keybind has been triggered. bool false
scroll_event_delay in ms, how many ms to wait after a scroll event to allow passing another one for the binds. int 300
workspace_back_and_forth If enabled, an attempt to switch to the currently focused workspace will instead switch to the previous workspace. Akin to i3's auto_back_and_forth. bool false
allow_workspace_cycles If enabled, workspaces don't forget their previous workspace, so cycles can be created by switching to the first workspace in a sequence, then endlessly going to the previous workspace. bool false
workspace_center_on Whether switching workspaces should center the cursor on the workspace (0) or on the last active window for that workspace (1) int 0
focus_preferred_method sets the preferred focus finding method when using focuswindow/movewindow/etc with a direction. 0 - history (recent have priority), 1 - length (longer shared edges have priority) int 0
ignore_group_lock If enabled, dispatchers like moveintogroup, moveoutofgroup and movewindoworgroup will ignore lock per group. bool false
movefocus_cycles_fullscreen If enabled, when on a fullscreen window, movefocus will cycle fullscreen, if not, it will move the focus in a direction. bool true
disable_keybind_grabbing If enabled, apps that request keybinds to be disabled (e.g. VMs) will not be able to do so. bool false
window_direction_monitor_fallback If enabled, moving a window or focus over the edge of a monitor with a direction will move it to the next monitor in that direction. bool true

XWayland

name description type default
use_nearest_neighbor uses the nearest neighbor filtering for xwayland apps, making them pixelated rather than blurry bool true
force_zero_scaling forces a scale of 1 on xwayland windows on scaled displays. bool false

OpenGL

name description type default
nvidia_anti_flicker reduces flickering on nvidia at the cost of possible frame drops on lower-end GPUs. On non-nvidia, this is ignored. bool true
force_introspection forces introspection at all times. Introspection is aimed at reducing GPU usage in certain cases, but might cause graphical glitches on nvidia. 0 - nothing, 1 - force always on, 2 - force always on if nvidia int 2

Render

name description type default
explicit_sync Whether to enable explicit sync support. Requires a hyprland restart. 0 - no, 1 - yes, 2 - auto based on the gpu driver int 2
explicit_sync_kms Whether to enable explicit sync support for the KMS layer. Requires explicit_sync to be enabled. 0 - no, 1 - yes, 2 - auto based on the gpu driver int 2
direct_scanout Enables direct scanout. Direct scanout attempts to reduce lag when there is only one fullscreen application on a screen (e.g. game). It is also recommended to set this to false if the fullscreen application shows graphical glitches. bool false

Cursor

name description type default
no_hardware_cursors disables hardware cursors bool false
no_break_fs_vrr disables scheduling new frames on cursor movement for fullscreen apps with VRR enabled to avoid framerate spikes (requires no_hardware_cursors = true) bool false
min_refresh_rate minimum refresh rate for cursor movement when no_break_fs_vrr is active. Set to minimum supported refresh rate or higher int 24
hotspot_padding the padding, in logical px, between screen edges and the cursor int 1
inactive_timeout in seconds, after how many seconds of cursor's inactivity to hide it. Set to 0 for never. int 0
no_warps if true, will not warp the cursor in many cases (focusing, keybinds, etc) bool false
persistent_warps When a window is refocused, the cursor returns to its last position relative to that window, rather than to the centre. bool false
warp_on_change_workspace If true, move the cursor to the last focused window after changing the workspace. bool false
default_monitor the name of a default monitor for the cursor to be set to on startup (see hyprctl monitors for names) str EMPTY
zoom_factor the factor to zoom by around the cursor. Like a magnifying glass. Minimum 1.0 (meaning no zoom) float 1.0
zoom_rigid whether the zoom should follow the cursor rigidly (cursor is always centered if it can be) or loosely bool false
enable_hyprcursor whether to enable hyprcursor support bool true
hide_on_key_press Hides the cursor when you press any key until the mouse is moved. bool false
hide_on_touch Hides the cursor when the last input was a touch input until a mouse input is done. bool true
allow_dumb_copy Makes HW cursors work on Nvidia, at the cost of a possible hitch whenever the image changes bool false

Debug

{{< callout type=warning >}}

Only for developers.

{{< /callout >}}

name description type default
overlay print the debug performance overlay. Disable VFR for accurate results. bool false
damage_blink (epilepsy warning!) flash areas updated with damage tracking bool false
disable_logs disable logging to a file bool true
disable_time disables time logging bool true
damage_tracking redraw only the needed bits of the display. Do not change. (default: full - 2) monitor - 1, none - 0 int 2
enable_stdout_logs enables logging to stdout bool false
manual_crash set to 1 and then back to 0 to crash Hyprland. int 0
suppress_errors if true, do not display config file parsing errors. bool false
watchdog_timeout sets the timeout in seconds for watchdog to abort processing of a signal of the main thread. Set to 0 to disable. int 5
disable_scale_checks disables verification of the scale factors. Will result in pixel alignment and rounding errors. bool false
error_limit limits the number of displayed config file parsing errors. int 5
error_position sets the position of the error bar. top - 0, bottom - 1 int 0
colored_stdout_logs enables colors in the stdout logs. bool true

More

There are more config options described in other pages, which are layout- or circumstance-specific. See the sidebar for more pages.