add-dock-band

# Add Dock Band Support The Command Palette Dock is a persistent toolbar at the edge of the user's screen. Your extension can provide **dock bands** — strips of items that appear in the Dock — giving users quick access to commands without opening the full Command Palette. ## When to Use This Skill - Adding a quick-access button to the persistent toolbar - Creating a multi-button toolbar strip - Displaying live-updating information (clock, CPU usage, etc.) - Providing frequently-used commands without opening the full palette ## Prerequisites - Command Palette Extension SDK version 0.9 or later (`Microsoft.CommandPalette.Extensions` ≥ 0.9.260303001) ## Quick Start: Single Button Dock Band Override `GetDockBands()` in your `CommandProvider`: ```csharp public partial class MyCommandsProvider : CommandProvider { private readonly ICommandItem[] _commands; private readonly ICommandItem _dockBand; public MyCommandsProvider() { DisplayName = "My Extension"; Id = "com.mycompany.myextension"; // Unique ID required for dock var mainPage = new MyPage(); _dockBand = new CommandItem(mainPage) { Title = DisplayName }; _commands = [new CommandItem(mainPage) { Title = DisplayName }]; } public override ICommandItem[] TopLevelCommands() => _commands; public override ICommandItem[]? GetDockBands() => [_dockBand]; } ``` ## Multi-Button Dock Band Use `WrappedDockItem` to create a band with multiple buttons: ```csharp public override ICommandItem[]? GetDockBands() { var button1 = new ListItem(new OpenUrlCommand("https://github.com")) { Title = "GitHub", Icon = new IconInfo("\uE774"), }; var button2 = new ListItem(new OpenUrlCommand("https://learn.microsoft.com")) { Title = "Learn", Icon = new IconInfo("\uE82D"), }; var band = new WrappedDockItem( [button1, button2], "com.mycompany.myextension.quicklinks", // Unique band ID "Quick Links"); return [band]; } ``` ## Live-Updating Dock Band Create a dock band that updates its content periodically (like a clock): ```csharp internal sealed partial class LiveStatusBand : ListItem { private readonly System.Timers.Timer _timer; public LiveStatusBand() : base(new NoOpCommand() { Result = CommandResult.KeepOpen() }) { Title = DateTime.Now.ToString("HH:mm"); Icon = new IconInfo("\uE823"); // Clock icon _timer = new System.Timers.Timer(60_000); // Update every minute _timer.Elapsed += (s, e) => { Title = DateTime.Now.ToString("HH:mm"); Subtitle = DateTime.Now.ToString("dddd, MMMM d"); }; _timer.Start(); } } // In CommandProvider: public override ICommandItem[]? GetDockBands() { var band = new WrappedDockItem( [new LiveStatusBand()], "com.mycompany.myextension.status", "Live Status"); return [band]; } ``` ## How Dock Bands Render | Command Type on ICommandItem | Dock Behavior | |------------------------------|---------------| | `IInvokableCommand` | Single button that executes the command | | `IListPage` | Each list item renders as a separate button in one band | | `IContentPage` | Single expandable button with a flyout | ## Support Pinning Nested Commands By default, only top-level commands and dock bands can be pinned. To allow pinning nested commands: ```csharp public override ICommandItem? GetCommandItem(string id) { // Look up commands by their Id foreach (var item in GetAllCommands()) { if (item?.Command is ICommand cmd && cmd.Id == id) return item; } return null; } ``` ## Important Notes - All dock band `ICommandItem` objects must have a `Command` with a **non-empty `Id`** — items without an ID are ignored - Set `Id` on your `CommandProvider` (e.g., `Id = "com.mycompany.myextension"`) - Use `WrappedDockItem` for multi-button bands backed by a `ListPage` - Keep dock band updates lightweight — they run frequently ## Documentation - [Adding Dock support](https://learn.microsoft.com/windows/powertoys/command-palette/adding-dock-support)