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:...
activewindowfloatingtiled
If no window is provided, the active window is used.
Workspaces
Workspaces can be referenced by:
- Name: E.g.,
1,42,Web,Anime,Better anime - Previous workspace:
previous, orprevious_per_monitor - Special Workspace:
specialorspecial:namefor named special workspaces. - Workspace object
- Workspace filters
- Workspace query
Note
In contexts where only special workspaces are accepted (e.g., the argument to hl.dsp.toggle_special()), do not include the special: workspace prefix.
This prefix is only needed in cases where a normal workspace would also be valid.
For example, hl.dsp.toggle_special("foo") targets the workspace typically referred to as special:foo.
Workspace filters
Workspaces that have already been created can be targeted by workspace filters (e.g., r[2-4] w[t1])
A filter is a sequence of filter expressions separated by spaces. No spaces are allowed inside expressions themselves.
r[A-B]- ID range from A to B inclusives[bool]- Whether the workspace is special or notn[bool],n[s:string],n[e:string]- named actions.n[bool]- whether a workspace is a named workspace.sandeare ‘starts with’ and ’ends with’, respectively.m[monitor]- Monitor selectorw[(flags)A-B],w[(flags)X]- Prop for window counts on the workspace.A-Bis an inclusive range;Xis a specific number. Flags can be omitted. Available flags are:tfor tiled-onlyffor floating-onlygto count groups instead of windowsvto count only visible windowspto 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.
Note
Filters can only target workspaces that already exist.
Trying to apply rules (for example persistent) to nonexistent workspaces will fail.
Workspace query
A workspace query is performed by suffixing a query selector with a signed offset, +n or -n, for a match relative to the active workspace.
To use an absolute, 1-indexed ID instead, ~ is put between selector and ID (e.g., m~3 is the third workspace on the current monitor).
| Selector | Description | Limits |
|---|---|---|
| e | Look on all monitors | Wraps around if range exceeds amount of worksapces in the direction |
| m | Look on current monitor | Wraps around if range exceeds amount of worksapces in the direction |
| r | Look on current monitor, including empty/nonexistent workspaces | [1 - …] |
| empty | Look for first empty workspace. Suffix with m to only look on current monitor, and/or n to find the next available empty workspace (e.g., emptynm) | Wraps around if it lands past the last numerical workspace, 2147483647 |
Warning
For query selectors that accept an ID, a sign or ~ is required.
m3 would be interpreted as a workspace name, not a query selector, and would do nothing unless there were a workspace named “m3”.
Direction
A direction.
l/left- leftr/right- rightu/up- upd/down- down
Monitor
Monitors can be selected by:
- Monitor object
- Monitor ID
- Output selector
- Direction
current