marceloeatworld/hyprland-ai-skill
hyprland
FlaggedThis skill should be used when the user asks about "Hyprland configuration", "hyprland.lua", "hyprland.conf", "Hyprland Lua config", "hyprctl", "Hyprland keybinds", "Hyprland window rules", "Hyprland monitors", "Hyprland dispatchers", "Hyprland animations", "Hyprland workspaces", "Hyprland IPC", "Hyprland plugins", "hyprlock", "hypridle", "hyprpaper", "hyprcursor", "hyprpicker", "hyprsunset", "xdg-desktop-portal-hyprland", "Hyprland on NixOS", "Hyprland Home Manager", "Hyprland layouts", "Hyprland dwindle", "Hyprland master layout", "Hyprland FAQ", "Hyprland performance", "Hyprland Nvidia", "Hyprland screen sharing", "Hyprland special workspace", "Hyprland smart gaps", "Hyprland multi-monitor", "Hyprland tearing", or any topic related to configuring, troubleshooting, or extending the Hyprland Wayland compositor and its ecosystem tools.
references/monitors.md
View on GitHub<!-- source: https://wiki.hypr.land/configuring/core/monitors -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->
# Hyprland Monitors Reference
---
weight: 10
title: Monitors
---
## Fields
All fields beyond `output` are optional and fall back to sensible defaults.
| Field | Description | Type | Default |
| --- | --- | --- | --- |
| output | Output name or `desc:...` description prefix | string | [[Required]] |
| disabled | Removes the monitor from the layout | bool | `false` |
| mode | Resolution and refresh rate (e.g. `"1920x1080@144"`). See the [note](./modes#modes) for predefined modes. Options: `mode`/`"preferred"`/`"highres"`/`"highrr"`/`"maxwidth"` | string | `"preferred"` |
| scale | Scale factor (e.g., `1.5`). `"auto"` = use monitor's PPI to decide the scale. Options: `scale`/`"auto"` | float/string | `"auto"` |
| transform | Rotation/flip transform (0–7) | int | 0 |
| position | Position in the virtual layout (e.g., `"1920x0"`). See the [note](./positioning#positions) for predefined positions | string | `"auto"` |
| mirror | Output name to mirror | string | [[Empty]] |
| bitdepth | Bit depth. Options: `8`/`10` | int | `8` |
| cm | Color management preset | string | `"srgb"` |
| sdr_eotf | SDR transfer function Options: `"default"`/`"gamma22"`/`"srgb"` | string | `"default"` |
| vrr | VRR modes | int | `0` |
| icc | Absolute path to an ICC profile | string | [[Empty]] |
| reserved_area | Reserved area: `int` for all sides or table | css_gaps | `0` |
| supports_wide_color | Force wide color gamut (-1 = off, 0 = auto, 1 = on) | int | `0` |
| supports_hdr | Force HDR support. -1 = off, 0 = auto, 1 = on. Options: [-1 - 1] | int | `0` |
| sdrbrightness | SDR brightness in HDR mode | float | `1.0` |
| sdrsaturation | SDR saturation in HDR mode | float | `1.0` |
| sdr_min_luminance | SDR minimum luminance for SDR→HDR mapping | float | `0.2` |
| sdr_max_luminance | SDR maximum luminance | int | `80` |
| min_luminance | Monitor minimum luminance | float | `-1` |
| max_luminance | Monitor maximum possible luminance | int | `-1` |
| max_avg_luminance | Monitor maximum average luminance | int | `-1` |
Leaving the `output` empty will define a fallback rule to use when no other rules match.
```lua
hl.monitor({ output = "", mode = "preferred", position = "auto", scale = 1 })
```
This will make any monitor that was not specified with an explicit rule be automatically placed on the right of the other(s), with its preferred resolution.
## General
To list all available monitors (active and inactive), use:
```bash
hyprctl monitors all
```
<!-- TODO: Describe reasons in "...BlockedBy" -->
{{% details title="Example output" closed="true" %}}
```
Monitor DP-3 (ID 0):
2560x1440@165.00000 at 0x0
description: AOC Q27G2G3R3B RTEN1HA009998
make: AOC
model: Q27G2G3R3B
physical size (mm): 600x340
serial: RTEN1HA009998
active workspace: 5 (5)
special workspace: 0 ()
reserved: 0 34 0 0
scale: 1
transform: 0
focused: yes
dpmsStatus: 1
vrr: false
solitary: 0
solitaryBlockedBy: windowed mode,missing candidate
activelyTearing: false
tearingBlockedBy: next frame is not torn,user settings,missing candidate
directScanoutTo: 0
directScanoutBlockedBy: windowed mode,missing candidate
disabled: false
currentFormat: XRGB2101010
mirrorOf: none
availableModes: 2560x1440@59.95Hz 2560x1440@165.00Hz 2560x1440@143.91Hz 2560x1440@120.00Hz 1920x1080@120.00Hz 1920x1080@119.88Hz 1920x1080@60.00Hz 1920x1080@60.00Hz 1920x1080@59.94Hz 1920x1080@50.00Hz 1280x1440@59.91Hz 1280x1024@75.03Hz 1280x1024@60.02Hz 1280x720@60.00Hz 1280x720@59.94Hz 1280x720@50.00Hz 1024x768@119.93Hz 1024x768@99.99Hz 1024x768@75.03Hz 1024x768@70.07Hz 1024x768@60.00Hz 832x624@74.55Hz 800x600@119.93Hz 800x600@99.86Hz 800x600@75.00Hz 800x600@72.19Hz 800x600@60.32Hz 800x600@56.25Hz 720x576@50.00Hz 720x576@50.00Hz 720x480@60.00Hz 720x480@60.00Hz 720x480@59.94Hz 720x480@59.94Hz 640x480@119.80Hz 640x480@99.83Hz 640x480@75.00Hz 640x480@72.81Hz 640x480@66.67Hz 640x480@60.00Hz 640x480@59.94Hz 640x480@59.94Hz 720x400@70.08Hz
colorManagementPreset: srgb
sdrBrightness: 1
sdrSaturation: 1
sdrMinLuminance: 0.2
sdrMaxLuminance: 80
hardwareCursorsInUse: true
```
{{% /details %}}
### Disabling a monitor
> [!WARNING]
> Disabling a monitor will remove it from the monitor layout, moving all windows and workspaces to any remaining ones.
> If you want to disable your monitor the way a screensaver does (just turning off the monitor), use the `dpms` [dispatcher](../dispatchers).
To disable a monitor, set `disabled = true`:
```lua
hl.monitor({ output = "name", disabled = true })
```
## Custom reserved area
A reserved area is an area that remains unoccupied by tiled windows.
If your workflow requires a custom reserved area, you can add it with the `reserved_area` field.
It accepts either a single integer (all sides) or a table with individual sides:
```lua
-- all sides
hl.monitor({ output = "name", reserved_area = 10 })
-- individual sides
hl.monitor({ output = "name", reserved_area = { top = 10, bottom = 10, left = 0, right = 0 } })
```
This stacks on top of the calculated reserved area (e.g., bars), but you may only use one of these rules per monitor in the config.
## Default workspace
See [Workspace Rules](../rules/workspace-rules).
### Binding workspaces to a monitor
See [Workspace Rules](../rules/workspace-rules).
---
---
weight: 10
title: Output selection
---
To select an output, a portname or a description (but not both) can be used.
Output of `hyprctl monitors` looks like the following:
```
Monitor `portname` (ID `ID`)
`mode` at `position`
description: `description`
[...]
```
Both `portname` and `description` can be used to select an output:
```lua
hl.monitor({
output = "portname",
mode = "preferred", position = "auto"
})
hl.monitor({
output = "desc:description",
mode = "preferred", position = "auto"
})
```
{{% details title="Example" closed="true" %}}
```
Monitor eDP-1 (ID 0):
1920x1080@60.00100 at 0x0
description: Chimei Innolux Corporation 0x150C
[...]
```
In the example, portname is `eDP-1` and description is `Chimei Innolux Corporation 0x150C`, so they can be used as follows:
```lua
hl.monitor({
output = "eDP-1",
mode = "preferred", position = "auto"
})
hl.monitor({
output = "desc:Chimei Innolux Corporation 0x150C",
mode = "preferred", position = "auto"
})
```
{{% /details %}}
---
---
weight: 30
title: Monitor modes
---
## Mode
Monitor mode is a combination of resolution and refresh rate.
To see available modes, run `hyprctl monitors` and find the `availableModes` field.
Modes are sorted by resolution in descending order.
Some modes may be duplicated or may have a skewed refresh rate.
### Modes
**Predefined modes cannot be combined**; only one can be selected.
- `preferred` - use the display's preferred size and refresh rate.
- `highres` - use the highest supported resolution.
- `highrr` - use the highest supported refresh rate.
- `maxwidth` - use the widest supported resolution.
## Custom modelines
You can set up a custom modeline by passing a modeline string as the `mode` field:
```lua
hl.monitor({
output = "DP-1",
mode = "modeline 1071.101 3840 3848 3880 3920 2160 2263 2271 2277 +hsync -vsync",
})
```
More about modelines can be read [here](https://wikipedia.org/wiki/XFree86_Modeline) and [here](https://wikipedia.org/wiki/Coordinated_Video_Timings)
## Mirrored displays
If you want to mirror a display, use the `mirror` field:
```lua
hl.monitor({ output = "DP-3", mode = "1920x1080@60", position = "0x0", scale = 1, mirror = "DP-2" })
hl.monitor({ output = "", mode = "preferred", position = "auto", scale = 1, mirror = "DP-1" })
```
Please remember that mirroring displays will not "re-render" everything for your second monitor, so if mirroring a 1080p screen onto a 4K one, the resolution will still be 1080p on the 4K display.
This also means squishing and stretching will occur on aspect ratios that differ (e.g., 16:9 and 16:10).
## VRR
VRR can be enabled globally or on a per-display basis.
Per-display VRR can be configured with the `vrr` field in `hl.monitor()` call.
Global config can be found in the [config options](../../config-options).
Available values:
- `-1` - follow global switch
- `0` - off
- `1` - on
- `2` - fullscreen only
- `3` - fullscreen with `video` or `game` content type
```lua
hl.monitor({ output = "DP-1", vrr = 3 })
```
---
---
weight: 20
title: Positioning
---
> [!WARNING]
> No monitors can overlap.
> Overlapping monitors will raise a warning and will not be registered.
## Position
The position is calculated with the scaled (and transformed) resolution, meaning if you want your 4K monitor with scale 2 to the left of your 1080p one, you'd use the position `1920x0` for the second screen (3840 / 2).
If the monitor is also rotated 90 degrees (vertical), you'd use `1080x0`.
"Invalid scale" warnings will pop up if your scale does not create valid logical pixels.
A valid scale must divide your resolution cleanly (without decimals).
For example:
- 1920×1080 / 1.5 = 1280×720 → ok
- 1920×1080 / 1.4 = 1371.4286×771.42857 → not ok.
### Positions
- `auto` - let Hyprland decide on a position.
By default, it places each new monitor to the right of existing ones, using the monitor's top left corner as the root point.
- `auto-right/left/up/down` - place the monitor to the right/left, above or below other monitors, also based on each monitor's top left corner as the root.
- `auto-center-right/left/up/down` - place the monitor to the right/left, above or below other monitors, but calculate placement from each monitor's center rather than its top left corner.
If direction in special position is specified for the first output in the monitor layout, it will be ignored and monitor will be placed at (0,0).
The direction is always from the center out, so you can specify `auto-up`, then `auto-left`, but the left monitors will just be left of the origin and above the origin.
You can also specify duplicate directions and monitors will continue to go in that direction.
{{% details title="Examples" closed="true" %}}
```lua
hl.monitor({ output = "DP-1", mode = "1920x1080@120Hz", position = "0x0", scale = 1 })
hl.monitor({ output = "DP-2", mode = "1920x1080@120Hz", position = "1920x0", scale = 1 })
```
will tell Hyprland to put DP-2 on the _right_ of DP-1, while
```lua
hl.monitor({ output = "DP-1", mode = "1920x1080@120Hz", position = "1920x0", scale = 1 })
hl.monitor({ output = "DP-2", mode = "1920x1080@120Hz", position = "0x0", scale = 1 })
```
will tell Hyprland to put DP-1 on the _right_ of DP-2.
The `position` may contain _negative_ values, so the above example could also be written as:
```lua
hl.monitor({ output = "DP-1", mode = "1920x1080@120Hz", position = "0x0", scale = 1 })
hl.monitor({ output = "DP-2", mode = "1920x1080@120Hz", position = "-1920x0", scale = 1 })
```
As another example,
```lua
hl.monitor({ output = "DP-1", mode = "1920x1080@120Hz", position = "0x0", scale = 1 })
hl.monitor({ output = "DP-2", mode = "1920x1080@120Hz", position = "0x-1080", scale = 1 })
```
will tell Hyprland to put DP-2 _above_ DP-1, while
```lua
hl.monitor({ output = "DP-1", mode = "1920x1080@120Hz", position = "0x0", scale = 1 })
hl.monitor({ output = "DP-2", mode = "1920x1080@120Hz", position = "0x1080", scale = 1 })
```
will tell Hyprland to put DP-2 _below_.
{{% /details %}}
## Rotation
If you want to rotate a monitor, use the `transform` field:
```lua
hl.monitor({ output = "eDP-1", mode = "2880x1800@90", position = "0x0", scale = 1, transform = 1 })
```
Transform values have the following meanings:
- 0: normal (no transforms)
- 1: 90 degrees
- 2: 180 degrees
- 3: 270 degrees
- 4: flipped
- 5: flipped + 90 degrees
- 6: flipped + 180 degrees
- 7: flipped + 270 degrees
---
---
weight: 40
title: Colors and colorspaces
---
## Color management presets
Use the `cm` field to change the default sRGB output preset:
```lua
hl.monitor({ output = "eDP-1", cm = "wide" })
```
Supported presets are:
```plain
auto - srgb for 8bpc, wide for 10bpc if supported (recommended)
srgb - sRGB primaries (default)
dcip3 - DCI P3 primaries
dp3 - Apple P3 primaries
adobe - Adobe RGB primaries
wide - wide color gamut, BT2020 primaries
edid - primaries from edid (known to be inaccurate)
hdr - wide color gamut and HDR PQ transfer function (experimental)
hdredid - same as hdr with edid primaries (experimental)
```
Fullscreen HDR is possible without the `hdr` cm setting if `render:cm_auto_hdr` is enabled.
Use `sdrbrightness` and `sdrsaturation` to control SDR brightness and saturation in HDR mode.
The default for both values is `1.0`.
Typical brightness value should be in the `1.0 - 2.0` range.
```lua
hl.monitor({
output = "eDP-1",
cm = "hdr",
sdrbrightness = 1.2,
sdrsaturation = 0.98,
})
```
The default transfer function assumed to be in use on an SDR display for sRGB content is defined by `sdr_eotf`.
The default (`"default"`) follows `render:cm_sdr_eotf`.
This can be changed to piecewise sRGB with `"srgb"`, or Gamma 2.2 with `"gamma22"`.
If your monitor supports it, `bitdepth = 10` is recommended for better colorspace handling.
## 10 bit support
> [!WARNING]
> Some monitors may state they have 10bit support, but in reality they emulate it with 8bit+[FRC](https://wikipedia.org/wiki/Frame_rate_control).
> Be aware that this may cause serious eye strain.
Colors registered in Hyprland (e.g. the border color) do _not_ support 10 bit.
Some applications do _not_ support screen capture with 10 bit enabled.
If you want to enable 10 bit support for your display, set `bitdepth = 10`:
```lua
hl.monitor({ output = "DP-1", bitdepth = 10 })
```
## ICC Profiles
You can load an ICC profile via the `icc` field (path must be absolute):
```lua
hl.monitor({ output = "DP-1", icc = "/path/to/icc.icm" })
```
Please note:
- Path needs to be absolute.
- Having an ICC applied will automatically force `sdr_eotf` to `sRGB` for that monitor (for color accuracy).
- Having an ICC applied overrides the CM preset.
- ICCs are fundamentally incompatible with HDR gaming. Funky stuff may happen.
---
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |