scratchpads

Easily toggle the visibility of applications you use the most.

Configurable and flexible, while supporting complex setups it's easy to get started with:

[scratchpads.name]
command = "command to run"
class = "the window's class"  # check: hyprctl clients | grep class
size = "<width> <height>"  # size of the window relative to the screen size

As an example, defining two scratchpads:

• term which would be a kitty terminal on upper part of the screen
• volume which would be a pavucontrol window on the right part of the screen

Example:

[scratchpads.term]
animation = "fromTop"
command = "kitty --class kitty-dropterm"
class = "kitty-dropterm"
size = "75% 60%"
max_size = "1920px 100%"
margin = 50

[scratchpads.volume]
animation = "fromRight"
command = "pavucontrol"
class = "org.pulseaudio.pavucontrol"
size = "40% 90%"
unfocus = "hide"
lazy = true

Shortcuts are generally needed:

bind = $mainMod,V,exec,pypr toggle volume
bind = $mainMod,A,exec,pypr toggle term
bind = $mainMod,Y,exec,pypr attach

Note that when class is provided, the window is automatically managed by pyprland. When you create a scratchpad called "name", it will be hidden in special:scratch_<name>.

Note

If you wish to have a more generic space for any application you may run, check toggle_special.

Commands

• toggle <scratchpad name> toggles the given scratchpads
  • use multiple space separated names to synchronize visibility based on the first scratchpad provided
• show <scratchpad name> shows the given scratchpad
• hide <scratchpad name> hides the given scratchpad
• attach toggles attaching/anchoring the currently focused window to the (last used) scratchpad

Note

In version 2.3.5 and up, you can use "*" as a scratchpad name to target every scratchpad when using show or hide. You'll need to quote or escape the * character to avoid interpretation from your shell.

Configuration

command

This is the command you wish to run in the scratchpad.

It supports Variables

animation (optional)

Type of animation to use, default value is "fromTop":

• null / "" (no animation)
• "fromTop" (stays close to top screen border)
• "fromBottom" (stays close to bottom screen border)
• "fromLeft" (stays close to left screen border)
• "fromRight" (stays close to right screen border)

size (recommended)

No default value.

Each time scratchpad is shown, window will be resized according to the provided values.

For example on monitor of size 800x600 and size= "80% 80%" in config scratchpad always have size 640x480, regardless of which monitor it was first launched on.

Format

String with "x y" (or "width height") values using some units suffix:

• percents relative to the focused screen size (% suffix), eg: 60% 30%
• pixels for absolute values (px suffix), eg: 800px 600px
• a mix is possible, eg: 800px 40%

class (recommended)

No default value.

Allows Pyprland prepare the window for a correct animation and initial positioning.

Important

This will set some rules to every matching class!

position (optional)

No default value, overrides the automatic margin-based position.

Sets the scratchpad client window position relative to the top-left corner.

Same format as size (see above)

Example of scratchpad that always seat on the top-right corner of the screen:

[scratchpads.term_quake]
command = "wezterm start --class term_quake"
position = "50% 0%"
size = "50% 50%"
class = "term_quake"

Note

If position is not provided, the window is placed according to margin on one axis and centered on the other.

multi (optional)

Added in 2.2.13

Defaults to true.

When set to false, only one client window is supported for this scratchpad. Otherwise other matching windows will be attached to the scratchpad.

In case your scratchpad application spawns multiple windows and run into troubles check the skip_windowrules option.

Advanced configuration

To go beyond the basic setup and have a look at every configuration item, you can read the following pages:

• Advanced contains options for fine-tuners or specific tastes (eg: i3 compatibility)
• Non-Standard contains options for "broken" applications like progressive web apps (PWA) or emacsclient, use only if you can't get it to work otherwise

You can also find more

Monitor specific overrides

Added in 2.0.6

You can use different settings for a specific screen. Most attributes related to the display can be changed (not command, class or process_tracking for instance).

Use the monitor.<monitor name> configuration item to override values, eg:

[scratchpads.music.monitor.eDP-1]
position = "30% 50%"
animation = "fromBottom"

You may want to inline it for simple cases:

[scratchpads.music]
monitor = {HDMI-A-1={size = "30% 50%"}}