monitors

Allows relative placement of monitors depending on the model ("description" returned by hyprctl monitors). Useful if you have multiple monitors connected to a video signal switch or using a laptop and plugging monitors having different relative positions.

TIP

This plugin also supports Niri. It will automatically detect the environment and use nirictl to apply the layout. Note that "hotplug_commands" and "unknown" commands may need adjustment for Niri (e.g. using sh -c '...' or Niri specific tools).

Syntax:

[monitors.placement]
"description match".placement = "other description match"

Example to set a Sony monitor on top of a BenQ monitor

[monitors.placement]
Sony.topOf = "BenQ"

## Character case is ignored, "_" can be added
Sony.Top_Of = ["BenQ"]

## Thanks to TOML format, complex configurations can use separate "sections" for clarity, eg:

[monitors.placement."My monitor brand"]
## You can also use "port" names such as *HDMI-A-1*, *DP-1*, etc...
leftOf = "eDP-1"

## lists are possible on the right part of the assignment:
rightOf = ["Sony", "BenQ"]

# When multiple targets are specified, only the first connected monitor
# matching a pattern is used as the reference.

## > 2.3.2: you can also set scale, transform & rate for a given monitor
[monitors.placement.Microstep]
rate = 100

Try to keep the rules as simple as possible, but relatively complex scenarios are supported.

NOTE

Check wlr layout UI which is a nice complement to configure your monitor settings.

Commands

Loading commands...

Configuration

Loading configuration...

placement

Configure monitor settings and relative positioning. Each monitor is identified by a pattern (port name or description substring) and can have both display settings and positioning rules.

[monitors.placement."My monitor"]
# Display settings
scale = 1.25
transform = 1
rate = 144
resolution = "2560x1440"

# Positioning
leftOf = "eDP-1"

Monitor Settings

These settings control the display properties of a monitor.

scale

Controls UI element size. Higher values make the UI larger (zoomed in), showing less content.

Scale Value	Content Visible
0.666667	More (zoomed out)
0.833333	More
1.0	Native
1.25	Less
1.6	Less
2.0	25% (zoomed in)

TIP

For HiDPI displays, use values like 1.5 or 2.0 to make UI elements larger and more readable at the cost of screen real estate.

transform

Rotates and optionally flips the monitor.

Value	Rotation	Description
0	Normal	No rotation (landscape)
1	90°	Portrait (rotated right)
2	180°	Upside down
3	270°	Portrait (rotated left)
4	Flipped	Mirrored horizontally
5	Flipped 90°	Mirrored + 90°
6	Flipped 180°	Mirrored + 180°
7	Flipped 270°	Mirrored + 270°

rate

Refresh rate in Hz.

rate = 144

TIP

Run hyprctl monitors to see available refresh rates for each monitor.

resolution

Display resolution. Can be specified as a string or array.

resolution = "2560x1440"
# or
resolution = [2560, 1440]

TIP

Run hyprctl monitors to see available resolutions for each monitor.

disables

List of monitors to disable when this monitor is connected. This is useful for automatically turning off a laptop's built-in display when an external monitor is plugged in.

[monitors.placement."External Monitor"]
disables = ["eDP-1"]  # Disable laptop screen when this monitor is connected

You can disable multiple monitors and combine with positioning rules:

[monitors.placement."DELL U2722D"]
leftOf = "DP-2"
disables = ["eDP-1", "HDMI-A-2"]

NOTE

Monitors specified in disables are excluded from layout calculations. They will be re-enabled on the next relayout if the disabling monitor is disconnected.

Positioning Rules

Position monitors relative to each other using directional keywords.

Directions:

• leftOf / rightOf — horizontal placement
• topOf / bottomOf — vertical placement

Alignment modifiers (for different-sized monitors):

• start (default) — align at top/left edge
• center / middle — center alignment
• end — align at bottom/right edge

Combine direction + alignment: topCenterOf, leftEndOf, right_middle_of, etc.

Everything is case insensitive; use _ for readability (e.g., top_center_of).

IMPORTANT

At least one monitor must have no placement rule to serve as the anchor/reference point. Other monitors are positioned relative to this anchor.

See Placement Examples for visual diagrams.

Monitor Patterns

Both the monitor being configured and the target monitor can be specified using:

1. Port name (exact match) — e.g., eDP-1, HDMI-A-1, DP-1
2. Description substring (partial match) — e.g., Hisense, BenQ, DELL P2417H

The plugin first checks for an exact port name match, then searches monitor descriptions for a substring match. Descriptions typically contain the manufacturer, model, and serial number.

# Target by port name
[monitors.placement.Sony]
topOf = "eDP-1"

# Target by brand/model name
[monitors.placement.Hisense]
top_middle_of = "BenQ"

# Mix both approaches
[monitors.placement."DELL P2417H"]
right_end_of = "HDMI-A-1"

TIP

Run hyprctl monitors (or nirictl outputs for Niri) to see the full description of each connected monitor.

startup_relayout

When set to false, do not initialize the monitor layout on startup or when configuration is reloaded.

relayout_on_config_change

When set to false, do not relayout when Hyprland config is reloaded.

new_monitor_delay

The layout computation happens after this delay when a new monitor is detected, to let time for things to settle.

hotplug_command

Allows to run a command when any monitor is plugged.

[monitors]
hotplug_command = "wlrlui -m"

hotplug_commands

Allows to run a command when a specific monitor is plugged.

Example to load a specific profile using wlr layout ui:

[monitors.hotplug_commands]
"DELL P2417H CJFH277Q3HCB" = "wlrlui rotated"

unknown

Allows to run a command when no monitor layout has been changed (no rule applied).

[monitors]
unknown = "wlrlui"

Placement Examples

This section provides visual diagrams to help understand monitor placement rules.

Basic Positions

The four basic placement directions position a monitor relative to another:

topOf - Monitor above another

[monitors.placement.A]
topOf = "B"

bottomOf - Monitor below another

[monitors.placement.A]
bottomOf = "B"

leftOf - Monitor to the left

[monitors.placement.A]
leftOf = "B"

rightOf - Monitor to the right

[monitors.placement.A]
rightOf = "B"

Alignment Modifiers

When monitors have different sizes, alignment modifiers control where the smaller monitor aligns along the edge.

Horizontal placement (leftOf / rightOf)

Start (default) - Top edges align:

[monitors.placement.A]
leftOf = "B"  # same as leftStartOf

Center / Middle - Vertically centered:

[monitors.placement.A]
leftCenterOf = "B"  # or leftMiddleOf

End - Bottom edges align:

[monitors.placement.A]
leftEndOf = "B"

Vertical placement (topOf / bottomOf)

Start (default) - Left edges align:

[monitors.placement.A]
topOf = "B"  # same as topStartOf

Center / Middle - Horizontally centered:

[monitors.placement.A]
topCenterOf = "B"  # or topMiddleOf

End - Right edges align:

[monitors.placement.A]
topEndOf = "B"

Common Setups

Dual side-by-side

[monitors.placement.A]
leftOf = "B"

Triple horizontal

[monitors.placement.A]
leftOf = "B"

[monitors.placement.C]
rightOf = "B"

Stacked (vertical)

[monitors.placement.A]
topOf = "B"

[monitors.placement.C]
bottomOf = "B"

Real-World Example: L-Shape with Portrait Monitor

This example shows a complex 3-monitor setup combining portrait mode, corner alignment, and different-sized displays.

Layout:

Where:

• A (HDMI-A-1) = Portrait monitor (transform=1), directly on top of B (blue)
• B (eDP-1) = Main anchor monitor, landscape (green)
• C = Landscape monitor, positioned at the bottom-right corner of A (orange)

Configuration:

[monitors.placement.CJFH277Q3HCB]
top_of = "eDP-1"
transform = 1
scale = 0.83

[monitors.placement.CJFH27888CUB]
right_end_of = "HDMI-A-1"

Explanation:

1. B (eDP-1) has no placement rule, making it the anchor/reference point
2. A (CJFH277Q3HCB) is placed on top of B with top_of = "eDP-1", rotated to portrait with transform = 1, and scaled to 83%
3. C (CJFH27888CUB) uses right_end_of = "HDMI-A-1" to position itself to the right of A with bottom edges aligned, creating the L-shape

The right_end_of placement is key here: it aligns C's bottom edge with A's bottom edge, tucking C into the corner rather than aligning at the top (which rightOf would do).