doc/dsc/modules/AlwaysOnTop.md
Manages configuration for the Always On Top utility, which pins windows to stay on top of other windows.
The AlwaysOnTop module configures PowerToys Always On Top, a utility that
allows you to pin any window to remain visible above all other windows. This
is useful for keeping reference materials, chat windows, or monitoring tools
visible while working with other applications.
The AlwaysOnTop module supports the following configurable properties:
Sets the keyboard shortcut to toggle Always On Top for the active window.
Type: object
Properties:
win (boolean) - Windows key modifier.ctrl (boolean) - Ctrl key modifier.alt (boolean) - Alt key modifier.shift (boolean) - Shift key modifier.code (integer) - Virtual key code.key (string) - Key name.Default: Win+Ctrl+T
Controls whether a colored border is displayed around pinned windows.
Type: boolean
Default: true
Sets the thickness of the border around pinned windows (in pixels).
Type: integer
Range: 1 to 100
Default: 5
Sets the color of the border around pinned windows.
Type: string (hex color)
Format: "#RRGGBB"
Default: "#FF0000" (red)
Sets the opacity of the border (0-100).
Type: integer
Range: 0 to 100
Default: 100
Controls whether to use the Windows accent color for the frame.
Type: boolean
Default: false
Controls whether a sound plays when toggling Always On Top.
Type: boolean
Default: false
Controls whether Always On Top is automatically disabled during game mode.
Type: boolean
Default: true
Controls whether the frame has rounded corners.
Type: boolean
Default: true
List of applications excluded from Always On Top functionality.
Type: string (newline-separated list of executable names)
This example enables Always On Top with default border appearance.
$config = @{
settings = @{
properties = @{
FrameEnabled = $true
FrameThickness = 5
FrameColor = "#FF0000"
FrameOpacity = 100
}
name = "AlwaysOnTop"
version = "1.0"
}
} | ConvertTo-Json -Depth 10 -Compress
PowerToys.DSC.exe set --resource 'settings' --module AlwaysOnTop `
--input $config
This example configures a custom border color and thickness.
dsc config set --file alwaysontop-appearance.dsc.yaml
# alwaysontop-appearance.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Customize Always On Top frame
type: Microsoft.PowerToys/AlwaysOnTopSettings
properties:
settings:
properties:
FrameEnabled: true
FrameThickness: 8
FrameColor: "#0078D7"
FrameOpacity: 80
RoundCornersEnabled: true
name: AlwaysOnTop
version: 1.0
This example installs PowerToys and configures Always On Top to use the Windows accent color.
winget configure winget-alwaysontop.yaml
# winget-alwaysontop.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
metadata:
winget:
processor: dscv3
resources:
- name: Install PowerToys
type: Microsoft.WinGet.DSC/WinGetPackage
properties:
id: Microsoft.PowerToys
source: winget
- name: Configure Always On Top
type: Microsoft.PowerToys/AlwaysOnTopSettings
properties:
settings:
properties:
FrameEnabled: true
FrameAccentColor: true
FrameThickness: 6
SoundEnabled: true
name: AlwaysOnTop
version: 1.0
This example ensures Always On Top is disabled during game mode.
# alwaysontop-gaming.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Configure for gaming
type: Microsoft.PowerToys/AlwaysOnTopSettings
properties:
settings:
properties:
DoNotActivateOnGameMode: true
name: AlwaysOnTop
version: 1.0
This example configures a subtle, thin border.
$config = @{
settings = @{
properties = @{
FrameEnabled = $true
FrameThickness = 2
FrameOpacity = 50
RoundCornersEnabled = true
}
name = "AlwaysOnTop"
version = "1.0"
}
} | ConvertTo-Json -Depth 10 -Compress
PowerToys.DSC.exe set --resource 'settings' --module AlwaysOnTop --input $config
This example excludes certain applications from Always On Top.
# alwaysontop-exclusions.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Exclude apps from Always On Top
type: Microsoft.PowerToys/AlwaysOnTopSettings
properties:
settings:
properties:
ExcludedApps: |
Game.exe
FullScreenApp.exe
name: AlwaysOnTop
version: 1.0
Keep documentation or reference windows visible:
resources:
- name: Reference window settings
type: Microsoft.PowerToys/AlwaysOnTopSettings
properties:
settings:
properties:
FrameEnabled: true
FrameColor: "#00FF00"
FrameOpacity: 60
name: AlwaysOnTop
version: 1.0
Pin monitoring tools and dashboards:
resources:
- name: Monitoring settings
type: Microsoft.PowerToys/AlwaysOnTopSettings
properties:
settings:
properties:
FrameEnabled: true
FrameAccentColor: true
SoundEnabled: false
name: AlwaysOnTop
version: 1.0