Skip to content
Configuring
Naming conventions

Naming conventions

Syntax

Tip

For ease of understanding, this wiki introduces a special syntax for some elements.

Optional parameters

Text followed by a question mark (?) indicates that the parameter is optional and may be omitted. If the question mark is followed by = data_type/= value, this means that the parameter can only take the specified data type or defaults to the specified value.

Example

hl.dsp.window.float({ window?, action? }) means that window and action are not required. The dispatcher will use their default values instead: the currently active window, and an action of "toggle".

Value ranges

[value1 - value2] means a range of values from value1 to value2 with respect to the type. If one of the limits is not specified, it is substituted with ....

Examples

[0.25 - 5.0] means all floating numbers from 0.25 to 5.0 are allowed.
[0 - ...] means all int values from 0 to your machine’s int limit are allowed.

Coordinates

Coordinates are in an inverse-Y Cartesian system, so moving to the right is the positive X direction (+x), and moving downward is the positive Y direction (+y).

Data types

typedescription
intInteger number
floatFloating point number
boolBoolean, true or false
stringLua string. Symbols wrapped in ""/[[]]/'' (e.g., "dwindle", 'master', [[scrolling]]). When using Lua literal strings ([[]]), escaping of " and ' is not needed
tableA Lua table, { }
vec2Vector with 2 float values. {x, y} (e.g., {20, 20})
css_gapsAn integer, or { top?, left?, right?, bottom? }
colorColor. See hint below for color info
gradientA gradient, will accept a color, or { colors = { color, color }, angle? = float } structure
font_weightAn integer between 100 and 1000, or one of the following presets: thin (100) ultralight (200) light (300) semilight (350) book (380) normal (400) medium (500) semibold (600) bold (700) ultrabold (800) heavy (900) ultraheavy (1000)

There are implicit conversions between certain types, however, this may lead to undefined behavior later. LSP with Lua stub can be used to warn about the use of wrong types. More on that can be read here.

Colors

You have 4 options:

  • Web-styled hash in RGB or RGBA form: "#FAFC32" or "#DDD" or "#FA3D7BFF"
  • rgba(): "rgba(57BBFFEE)", or decimal equivalent "rgba(87,187,255,0.933)"
  • rgb(): "rgb(FF4410)", or decimal equivalent "rgb(255,68,16)"
  • Legacy ARGB format: "0xeeb3ff1a"

Note that decimal arguments in rgb()/rgba() should have no spaces between them.

Selectors

Any ID can be selected by using either of the following two selectors:

  • Relative selection via + or -
  • Absolute selection via the ID itself

RegEx selector

Hyprland uses Google’s RE2 for parsing RegEx. This means that all operations requiring polynomial time to compute will not work. See the RE2 wiki for supported extensions.

To learn more about supported regex constructs, refer to this cheatsheet.

If you want to negate a RegEx, as in pass only when the RegEx fails, you can prefix it with negative: (e.g., "negative:kitty")

Tip

Lua’s literal-string [[]] syntax may be helpful to avoid “backslash hell”. For example, you might write [[\b\w*apple\b]] instead of "\\b\\w*apple\\b".

Window selector

Windows can be selected by:

  • Window object
  • Exact selectors:
    • pid:...
    • stableid:...
    • address:0x...
  • Regexes:
    • class:...
    • initialclass:...
    • title:...
    • initialtitle:...
    • tag:...
  • activewindow
  • floating
  • tiled

If no window is provided, the active window is used.

Workspace selectors

Warning

Numerical workspaces (e.g., 1, 2, 13371337) are allowed ONLY between 1 and 2147483647, inclusive. Neither 0 nor negative numbers are allowed.

Workspaces can be selected by:

  • Workspace object

  • Workspace ID

  • Workspace prop

  • Workspace search

  • Name: E.g., name:Web, name:Anime, name:Better anime

  • Previous workspace: previous, or previous_per_monitor

  • Special Workspace: special or special:name for named special workspaces.

Workspace props

Workspaces that have already been created can be targeted by workspace selectors (e.g., r[2-4] w[t1])

Props separated by a space. No spaces are allowed inside props themselves.

  • r[A-B] - ID range from A to B inclusive
  • s[bool] - Whether the workspace is special or not
  • n[bool], n[s:string], n[e:string] - named actions. n[bool] - whether a workspace is a named workspace. s and e are ‘starts with’ and ’ends with’, respectively.
  • m[monitor] - Monitor selector
  • w[(flags)A-B], w[(flags)X] - Prop for window counts on the workspace. A-B is an inclusive range; X is a specific number. Flags can be omitted. Available flags are:
    • t for tiled-only
    • f for floating-only
    • g to count groups instead of windows
    • v to count only visible windows
    • p to count only pinned windows
  • f[-1], f[0], f[1], f[2] - fullscreen state of the workspace. -1: no fullscreen, 0: fullscreen, 1: maximized, 2: fullscreen without sending fullscreen state to the window. Only matches workspaces with covering fullscreen windows.

Workspace search

Workspace search is performed by suffixing search selector with workspace ID. To use absolute ID, ~ is put between selector and ID (e.g., m~3)

  • m - Search for workspace on current monitor
  • r - Search for workspace on current monitor including empty/non-existant workspaces
  • e - Search on all monitors
  • empty - Search for first empty workspace. Suffix with m to only search on monitor, and/or n to make it the next available empty workspace (e.g., emptynm)

Direction

A direction.

  • l/left - left
  • r/right - right
  • u/up - up
  • d/down - down

Monitor

Monitors can be selected by:

Last updated on
Lua code snippets