In thelayout {} section you can change various settings that influence how windows are positioned and sized.

Here are the contents of this section at a glance:

layout {    gaps16    center-focused-column"never"    always-center-single-column    empty-workspace-above-first    default-column-display"tabbed"    background-color"#003300"    preset-column-widths {        proportion0.33333        proportion0.5        proportion0.66667    }    default-column-width { proportion0.5; }    preset-window-heights {        proportion0.33333        proportion0.5        proportion0.66667    }    focus-ring {// off        width4        active-color"#7fc8ff"        inactive-color"#505050"        urgent-color"#9b0000"// active-gradient from="#80c8ff" to="#bbddff" angle=45// inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view"// urgent-gradient from="#800" to="#a33" angle=45    }    border {        off        width4        active-color"#ffc87f"        inactive-color"#505050"        urgent-color"#9b0000"// active-gradient from="#ffbb66" to="#ffc880" angle=45 relative-to="workspace-view"// inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view" in="srgb-linear"// urgent-gradient from="#800" to="#a33" angle=45    }    shadow {// on        softness30        spread5        offsetx=0y=5        draw-behind-windowtrue        color"#00000070"// inactive-color "#00000054"    }    tab-indicator {// off        hide-when-single-tab        place-within-column        gap5        width4        lengthtotal-proportion=1.0        position"right"        gaps-between-tabs2        corner-radius8        active-color"red"        inactive-color"gray"        urgent-color"blue"// active-gradient from="#80c8ff" to="#bbddff" angle=45// inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view"// urgent-gradient from="#800" to="#a33" angle=45    }    insert-hint {// off        color"#ffc87f80"// gradient from="#ffbb6680" to="#ffc88080" angle=45 relative-to="workspace-view"    }    struts {// left 64// right 64// top 64// bottom 64    }}

Set gaps around (inside and outside) windows in logical pixels.

^{Since: 0.1.7} You can use fractional values.The value will be rounded to physical pixels according to the scale factor of every output.For example,gaps 0.5 on an output withscale 2 will result in one physical-pixel wide gaps.

^{Since: 0.1.8} You can emulate "inner" vs. "outer" gaps with negativestruts values (see the struts section below).

layout {    gaps16}

When to center a column when changing focus.This can be set to:

• "never": no special centering, focusing an off-screen column will scroll it to the left or right edge of the screen. This is the default.
• "always", the focused column will always be centered.
• "on-overflow", focusing a column will center it if it doesn't fit on screen together with the previously focused column.

layout {    center-focused-column"always"}

^{Since: 0.1.9}

If set, niri will always center a single column on a workspace, regardless of thecenter-focused-column option.

layout {    always-center-single-column}

^{Since: 25.01}

If set, niri will always add an empty workspace at the very start, in addition to the empty workspace at the very end.

layout {    empty-workspace-above-first}

^{Since: 25.02}

Sets the default display mode for new columns.Can benormal ortabbed.

// Make all new columns tabbed by default.layout {    default-column-display"tabbed"// You may also want to hide the tab indicator// when there's only a single window in a column.    tab-indicator {        hide-when-single-tab    }}

Set the widths that theswitch-preset-column-width action (Mod+R) toggles between.

proportion sets the width as a fraction of the output width, taking gaps into account.For example, you can perfectly fit four windows sizedproportion 0.25 on an output, regardless of the gaps setting.The default preset widths are¹⁄₃,¹⁄₂ and²⁄₃ of the output.

fixed sets the window width in logical pixels exactly.

layout {// Cycle between 1/3, 1/2, 2/3 of the output, and a fixed 1280 logical pixels.    preset-column-widths {        proportion0.33333        proportion0.5        proportion0.66667        fixed1280    }}

Set the default width of the new windows.

The syntax is the same as inpreset-column-widths above.

layout {// Open new windows sized 1/3 of the output.    default-column-width { proportion0.33333; }}

You can also leave the brackets empty, then the windows themselves will decide their initial width.

layout {// New windows decide their initial width themselves.    default-column-width {}}

^{Since: 0.1.9}

Set the heights that theswitch-preset-window-height action (Mod+Shift+R) toggles between.

proportion sets the height as a fraction of the output height, taking gaps into account.The default preset heights are¹⁄₃,¹⁄₂ and²⁄₃ of the output.

fixed sets the height in logical pixels exactly.

layout {// Cycle between 1/3, 1/2, 2/3 of the output, and a fixed 720 logical pixels.    preset-window-heights {        proportion0.33333        proportion0.5        proportion0.66667        fixed720    }}

Focus ring and border are drawn around windows and indicate the active window.They are very similar and have the same options.

The difference is that the focus ring is drawn only around the active window, whereas borders are drawn around all windows and affect their sizes (windows shrink to make space for the borders).

Focus Ring	Border

Focus ring and border have the following options.

layout {// focus-ring has the same options.    border {// Uncomment this line to disable the border.// off// Width of the border in logical pixels.        width4        active-color"#ffc87f"        inactive-color"#505050"// Color of the border around windows that request your attention.        urgent-color"#9b0000"// active-gradient from="#ffbb66" to="#ffc880" angle=45 relative-to="workspace-view"// inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view" in="srgb-linear"    }}

Set the thickness of the border in logical pixels.

^{Since: 0.1.7} You can use fractional values.The value will be rounded to physical pixels according to the scale factor of every output.For example,width 0.5 on an output withscale 2 will result in one physical-pixel thick borders.

layout {    border {        width2    }}

Colors can be set in a variety of ways:

• CSS named colors:"red"
• RGB hex:"#rgb","#rgba","#rrggbb","#rrggbbaa"
• CSS-like notation:"rgb(255, 127, 0)","rgba()","hsl()" and a few others.

active-color is the color of the focus ring / border around the active window, andinactive-color is the color of the focus ring / border around all other windows.

Thefocus ring is only drawn around the active window on each monitor, so with a single monitor you will never see itsinactive-color.You will see it if you have multiple monitors, though.

There's also adeprecated syntax for setting colors with four numbers representing R, G, B and A:active-color 127 200 255 255.

Similarly to colors, you can setactive-gradient andinactive-gradient, which will take precedence.

Gradients are rendered the same as CSSlinear-gradient(angle, from, to).The angle works the same as inlinear-gradient, and is optional, defaulting to180 (top-to-bottom gradient).You can use any CSS linear-gradient tool on the web to set these up, likecss-gradient.com.

layout {    focus-ring {        active-gradientfrom="#80c8ff"to="#bbddff"angle=45    }}

Gradients can be colored relative to windows individually (the default), or to the whole view of the workspace.To do that, setrelative-to="workspace-view".Here's a visual example:

Default	relative-to="workspace-view"

layout {    border {        active-gradientfrom="#ffbb66"to="#ffc880"angle=45relative-to="workspace-view"        inactive-gradientfrom="#505050"to="#808080"angle=45relative-to="workspace-view"    }}

^{Since: 0.1.8} You can set the gradient interpolation color space using syntax likein="srgb-linear" orin="oklch longer hue".Supported color spaces are:

• srgb (the default),
• srgb-linear,
• oklab,
• oklch withshorter hue orlonger hue orincreasing hue ordecreasing hue.

They are rendered the same as CSS.For example,active-gradient from="#f00f" to="#0f05" angle=45 in="oklch longer hue" will look the same as CSSlinear-gradient(45deg in oklch longer hue, #f00f, #0f05).

layout {    border {        active-gradientfrom="#f00f"to="#0f05"angle=45in="oklch longer hue"    }}

^{Since: 25.02}

Shadow rendered behind a window.

Seton to enable the shadow.

softness controls the shadow softness/size in logical pixels, same asCSS box-shadowblur radius.Settingsoftness 0 will give you hard shadows.

spread is the distance to expand the window rectangle in logical pixels, same as CSS box-shadow spread.^{Since: 25.05} Spread can be negative.

offset moves the shadow relative to the window in logical pixels, same as CSS box-shadow offset.For example,offset x=2 y=2 will move the shadow 2 logical pixels downwards and to the right.

Setdraw-behind-window totrue to make shadows draw behind the window rather than just around it.Note that niri has no way of knowing about the CSD window corner radius.It has to assume that windows have square corners, leading to shadow artifacts inside the CSD rounded corners.This setting fixes those artifacts.

However, instead you may want to setprefer-no-csd and/orgeometry-corner-radius.Then, niri will know the corner radius and draw the shadow correctly, without having to draw it behind the window.These will also remove client-side shadows if the window draws any.

color is the shadow color and opacity.

inactive-color lets you override the shadow color for inactive windows; by default, a more transparentcolor is used.

Shadow drawing will follow the window corner radius set with thegeometry-corner-radius window rule.

// Enable shadows.layout {    shadow {        on    }}// Also ask windows to omit client-side decorations, so that// they don't draw their own window shadows.prefer-no-csd

^{Since: 25.02}

Controls the appearance of the tab indicator that appears next to columns in tabbed display mode.

Setoff to hide the tab indicator.

Sethide-when-single-tab to hide the indicator for tabbed columns that only have a single window.

Setplace-within-column to put the tab indicator "within" the column, rather than outside.This will include it in column sizing and avoid overlaying adjacent columns.

gap sets the gap between the tab indicator and the window in logical pixels.The gap can be negative, this will put the tab indicator on top of the window.

width sets the thickness of the indicator in logical pixels.

length controls the length of the indicator.Set thetotal-proportion property to make tabs take up this much length relative to the window size.By default, the tab indicator has length equal to half of the window size, orlength total-proportion=0.5.

position sets the position of the tab indicator relative to the window.It can beleft,right,top, orbottom.

gaps-between-tabs controls the gap between individual tabs in logical pixels.

corner-radius sets the rounded corner radius for tabs in the indicator in logical pixels.Whengaps-between-tabs is zero, only the first and the last tabs have rounded corners, otherwise all tabs do.

active-color,inactive-color,urgent-color,active-gradient,inactive-gradient,urgent-gradient let you override the colors for the tabs.They have the same semantics as the border and focus ring colors and gradients.

Tab colors are picked in this order:

1. Colors from thetab-indicator window rule, if set.
2. Colors from thetab-indicator layout options, if set (you're here).
3. If neither are set, niri picks the color matching the window border or focus ring, whichever one is active.

// Make the tab indicator wider and match the window height,// also put it at the top and within the column.layout {    tab-indicator {        width8        gap8        lengthtotal-proportion=1.0        position"top"        place-within-column    }}

^{Since: 0.1.10}

Settings for the window insert position hint during an interactive window move.

off disables the insert hint altogether.

color andgradient let you change the color of the hint and have the same syntax as colors and gradients in border and focus ring.

layout {    insert-hint {// off        color"#ffc87f80"        gradientfrom="#ffbb6680"to="#ffc88080"angle=45relative-to="workspace-view"    }}

Struts shrink the area occupied by windows, similarly to layer-shell panels.You can think of them as a kind of outer gaps.They are set in logical pixels.

Left and right struts will cause the next window to the side to always peek out slightly.Top and bottom struts will simply add outer gaps in addition to the area occupied by layer-shell panels and regular gaps.

^{Since: 0.1.7} You can use fractional values.The value will be rounded to physical pixels according to the scale factor of every output.For example,top 0.5 on an output withscale 2 will result in one physical-pixel wide top strut.

layout {    struts {        left64        right64        top64        bottom64    }}

^{Since: 0.1.8} You can use negative values.They will push the windows outwards, even outside the edges of the screen.

You can use negative struts with matching gaps value to emulate "inner" vs. "outer" gaps.For example, use this for inner gaps without outer gaps:

layout {    gaps16    struts {        left-16        right-16        top-16        bottom-16    }}

^{Since: 25.05}

Set the default background color that niri draws for workspaces.This is visible when you're not using any background tools like swaybg.

layout {    background-color"#003300"}

You can also set the color per-outputin the output config.