TIP 610: Icon Badges

Bounty program for improvements to Tcl and certain Tcl packages.
Author:         Kevin Walzer <[email protected]>
State:          Voting
Type:           Project
Created:        21-August-2021
Keywords:       Tk, desktop integration
Tcl-Version:    8.7
Keywords:		Tk, desktop integration


A widely implelmented UI element in desktop and mobile applications is an "icon badge," a small image laid over an application icon in a dock, panel or taskbar to indicate a change of state or provide notification of an update. The badge is typically removed when the application is brought into focus. A common example of this is a numeric image on an email program that indicates the number of new or unread messages. This TIP proposes to add a "wm iconbadge" command to Tk to provide this functionality.


The X11 implementation will be based on the "wm iconphoto" command and incorporate additional custom badge images that will be shipped with Tk.

The Windows implementation will use the custom badge images developed for this TIP and render them via the native "ITaskbarList3::SetOverlayIcon" API.

The Mac version will be completely native and implement a Tk wrapper over the NSDockTile API.

The wm iconbadge command will present a script-level public API implementing the proposed interface, outlined below.

wm iconbadge window badge

This command sets an icon badge over Wish's application icon as it appears in the Dock (macOS), taskbar (Windows) or application panel (X11). The "badge" argument at present is either a number to indicate a number of new messages or other data points, or an exclamation point to indicate a general call to attention. If the "badge" argument is set to an empty string, the badge icon is removed.

Moreover, the wm iconphoto window command will now return the current image set for the titlebar icon (instead of returning an error).


To set a badge icon with the number five over the application icon:

wm iconbadge . 5

To remove the badge:

wm iconbadge . ""

A full demonstration of this command in action has been added to the Tk widget demo under the "Miscellaneous" section, "Window icons and badges." Since the API is very simple, one can get a better understanding of the functionality by actually testing it in the demo.

Screenshot of the wm iconbadge on all three platforms:



A draft implementation is currently under development in the tk_badges branch.


This document has been placed in the public domain.