WinToast puts Windows toast notifications into a desktop C++ app

Modern toasts for a classic desktop application

WinToast is described as a lightweight library written in C++ that brings a complete integration of the modern toast notifications of Windows 8, Windows 10 and Windows 11. The purpose of the notification is stated plainly: it lets an app inform users about relevant information and timely events that they should see and take action upon inside the app, such as a new instant message, a new friend request, breaking news or a calendar event. The problem it solves is a specific one on Windows. The toast surface is a shell feature, and the usual way to reach it from a traditional Win32 or Qt application is not the modern packaged app model, so a desktop program that wants a proper notification in the Action Center ends up writing plumbing. This library is that plumbing, packaged as a C++ library with a small surface.

The eight templates map to the classic enumeration

The template support is the first thing the README explains, and it is a direct mapping onto the `ToastTemplateType` enumeration from the Windows documentation. Eight templates are integrated, and the table in the README gives each one a description. The four `ImageAndText` variants pair a large image with text: `ImageAndText01` is a single string wrapped across three lines, `ImageAndText02` puts one string of bold text on the first line with a regular string across the second and third, `ImageAndText03` puts the bold string across the first two lines, and `ImageAndText04` puts a bold first line followed by two regular lines. The four `Text` variants are the same without an image. Setting the fields is a matter of constructing the template and calling setters, and the README's `ImageAndText02` example shows the whole shape:

WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField(L"title", WinToastTemplate::FirstLine);
templ.setTextField(L"subtitle", WinToastTemplate::SecondLine);
templ.setImagePath(L"C:/example.png");

The sound and the image follow the system defaults, since Windows uses the app icon unless a sound is specified.

Activation, dismissal and failure arrive as callbacks

The event model is where a toast stops being decoration and starts being a channel back into the app. WinToast handles three events. Activated occurs when the user activates a toast notification through a click or touch, and the README notes that apps that are running subscribe to this event. Dismissed occurs when the toast leaves the screen, either by expiring or being explicitly dismissed, and it carries a reason: the application hid the toast, the user cancelled it, or it timed out. Failed occurs when Windows itself errors while trying to raise the notification. You implement these by subclassing the `IWinToastHandler` interface:

class WinToastHandlerExample : public IWinToastHandler {
 public:
	WinToastHandlerExample(); 
	// Public interfaces
	void toastActivated() const override;
	void toastActivated(int actionIndex) const override;
	void toastDismissed(WinToastDismissalReason state) const override;
	void toastFailed() const override;
};

The overload taking an `actionIndex` is the one that matters for an interactive toast, since it tells the app which button the user pressed rather than only that they pressed one.

Scenarios, expiration and the hint crop

The notification content section covers the properties that decide how urgent a toast looks and how long it lives. A scenario is how you mark an important notification, and the README lists four possible values, Reminder, Alarm, IncomingCall and Urgent, noting that the scenario adjusts a few behaviours to create a consistent experience. Expiration time sets when the toast stops being current, although the README points out that Windows tries to raise the notification immediately after you call Show, so the property is rarely used, and that for Windows 8.x apps it also removes the toast from the Action Center at the given time. The default Windows behaviour is to hide notifications automatically after the interval set in Ease of Access Settings, and to keep a notification in the Action Center longer you call `WinToastTemplate::setExpiration`. Hint crop is a small typographic detail with a Microsoft style rationale: a circular crop for profile pictures gives a consistent representation of people across apps.

WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField(L"Matt sent you a friend request", WinToastTemplate::FirstLine);
templ.setTextField(L"Hey, wanna dress up as wizards and ride around on hoverboards?", WinToastTemplate::SecondLine);
templ.setImagePath(L"C:/example.png");
templ.setHintCrop(WinToastTemplate::Circle);

The hero image, a large image at the top of the toast, is optional and can give the user extra context, with the README noting it is not supported on the oldest Windows 8.1 target.

The example projects cover console and Qt

The repository ships two example applications, and between them they show the two shapes of consumer that matter. There is a `console-example` and a `qt-gui-example`, with a shared `examples/CMakeLists.txt` at the top of that directory. That pairing is informative in itself. A toast library is only as useful as the integration it supports, and a console example is the awkward case where there is no window to own the notification, while the Qt example is the common case for a desktop tool. The README's table of contents also lists sections for error handling, for a full example of usage, for installation, and for toast configuration on Windows 10, which in the version of the documentation available here is truncated before the steps, and for a list of projects using WinToast. The documentation for those parts is on the project's documentation site rather than in the README body.

The repository is a plain library with a CMake build

The layout is conventional and small. At the root there is a `CMakeLists.txt`, a `LICENSE.txt`, a `README.md`, an `include/` directory holding the public headers, a `src/` directory with the implementation, an `examples/` directory, a `docs/` directory and an `assets/` directory for the images used in the README, plus a `request.md` file and a `_config.yml`. There is a `.clang-format` file and an `.editorconfig`, so the project pins its own formatting rules, and a `.github/` directory for the workflows. The library is C++ and the topics list mentions C++17, and the toast integration itself is inherently tied to the Windows platform, since the toast system is a Windows shell feature and the library is about bridging a desktop application to it.

MIT licensed, with a release line that moved on Windows 11

The licence is MIT, which in short terms means you can use, copy, modify and redistribute the library, including in commercial products, provided the notice and the licence text travel with it. The release history shows the project tracking Windows releases over the years. The listed versions are v1.3.0 from 2023-04-08, v1.3.1 from 2025-03-12 and v1.3.2 from 2025-07-10, and the last push to the repository was on 2026-04-20, so the code is not being archived and the working tree is current. Two caveats are worth stating for anyone evaluating it now. The README is written around the classic toast template model rather than the adaptive toast XML that Windows 10 introduced, so a project that needs the newer adaptive format has to look elsewhere. And the platform setup steps, such as how the toast configuration has to be set up on Windows 10, are described in sections of the documentation that the README links rather than in the README body itself, so they need to be read before you plan the deployment of a packaged or unpackaged application.

Editorial conclusion

Adopt WinToast when you are writing a native Windows desktop application in C++ and need the modern toast surface, since the library covers the standard templates, the click and dismissal events, and the content options Windows exposes, without pulling in a UWP packaging model. Do not adopt it if your application is already a packaged store app with its own notification API, or if you need the adaptive toast XML that Windows 10 introduced, because the library is built around the classic template enumeration. Verify first which Windows versions you must support, since parts of the content model such as the hero image are not available on the oldest ones, and read the installation and toast configuration sections that the README links for the platform setup steps.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mohabouje/WinToast on GitHub
4. README
5. Releases