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 = "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

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

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.

Helps Pyprland identify the window for a correct animation. Required if you are using the class_match option.

Important

This will set some rules to every matching class!

unfocus (optional)

No default value.

When set to "hide", allow to hide the window when the focus is lost.

Use hysteresis to change the reactivity

hysteresis (optional)

Defaults to 0.4 (seconds)

Controls how fast a scratchpad hiding on unfocus will react. Check unfocus option. Set to 0 to disable (immediate reaction, as in versions < 2.0.1)

Important

Only relevant when unfocus="hide" is used.

Note

Added in 2.0.1

margin (optional)

default value is 60.

number of pixels separating the scratchpad from the screen border, depends on the animation set.

[!info] Since version 2.2.4 it is also possible to set a string to express percentages of the screen (eg: '3%').

lazy (optional)

default to false.

when set to true, prevents the command from being started when pypr starts, it will be started when the scratchpad is first used instead.

• Good: saves resources when the scratchpad isn't needed
• Bad: slows down the first display (app has to launch before showing)

max_size (optional)

No default value.

Same format as size (see above), only used if size is also set.

Limits the size of the window accordingly. To ensure a window will not be too large on a wide screen for instance:

size = "60% 30%"
max_size = "1200px 100%"

excludes (optional)

No default value.

List of scratchpads to hide when this one is displayed, eg: excludes = ["term", "volume"]. If you want to hide every displayed scratch you can set this to the string "*" instead of a list: excludes = "*".

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.

preserve_aspect (optional)

Not set by default. When set to true, will preserve the size and position of the scratchpad when called repeatedly from the same monitor and workspace even though an animation , position or size is used (those will be used for the initial setting only).

Forces the lazy option.

Note

Added in 2.0.7

offset (optional)

In pixels, default to 0 (client's window size + margin).

Number of pixels for the hide sliding animation (how far the window will go).

Tip

• Since version 2.2.4 it is also possible to set a string to express percentages of the client window
• margin is automatically added to the offset
• automatic (value not set) is same as "100%"

hide_delay (optional)

Defaults to 0.2

Delay (in seconds) after which the hide animation happens, before hiding the scratchpad.

Rule of thumb, if you have an animation with speed "7", as in:

    animation = windowsOut, 1, 7, easeInOut, popin 80%

You can divide the value by two and round to the lowest value, here 3, then divide by 10, leading to hide_delay = 0.3.

Note

Added in 2.2.4

restore_focus (optional)

Enabled by default, set to false if you don't want the focused state to be restored when a scratchpad is hidden.

force_monitor (optional)

If set to some monitor name (eg: "DP-1"), it will always use this monitor to show the scratchpad.

Note

Added in 2.1.1

class_match (use only if really needed)

Default value is false.

If set to true, matches the client window using the provided WM_CLASS instead of the PID of the process.

Use it in case of troubles - check this wiki page

Requires class to be set to a matching window.

process_tracking (use only if really needed)

Default value is true

Allows disabling the process management. Use only if running a progressive web app (Chrome based apps) or similar. Check this wiki page for some details.

This will automatically force lazy = false and class_match = true to help with the fuzzy client window matching.

It requires defining a class option.

# Chat GPT on Brave
[scratchpads.gpt]
animation = "fromTop"
command = "brave --profile-directory=Default --app=https://chat.openai.com"
class = "brave-chat.openai.com__-Default"
size = "75% 60%"
process_tracking = false

# Some chrome app
[scratchpads.music]
command = "google-chrome --profile-directory=Default --app-id=cinhimbnkkaeohfgghhklpknlkffjgod"
class = "chrome-cinhimbnkkaeohfgghhklpknlkffjgod-Default"
size = "50% 50%"

Tip

To list windows by class and title you can use:

• hyprctl -j clients | jq '.[]|[.class,.title]'
• or if you prefer a graphical tool: rofi -show window

alt_toggle (optional)

Default value is false

When enabled, use an alternative toggle command logic for multi-screen setups. It applies when the toggle command is triggered and the toggled scratchpad is visible on a screen which is not the focused one.

Instead of moving the scratchpad to the focused screen, it will hide the scratchpad.

Note

Added in 2.2.4

Monitor specific overrides

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).

Note

Added in 2.0.6

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%"}}