PyQt Toast
![License](https://img.shields.io/badge/license-MIT-green)
A fully customizable and modern toast notification library for PyQt and PySide
![pyqttoast](https://github.com/niklashenning/pyqt-toast/assets/58544929/c104f10e-08df-4665-98d8-3785822a20dc)
Features
- Supports showing multiple toasts at the same time
- Supports queueing of toasts
- Supports 7 different positions
- Supports multiple screens
- Supports positioning relative to widgets
- Modern and fully customizable UI
- Works with
PyQt5
, PyQt6
, PySide2
, and PySide6
Installation
pip install pyqt-toast-notification
Usage
Import the Toast
class, instantiate it, and show the toast notification with the show()
method:
from PyQt6.QtWidgets import QMainWindow, QPushButton
from pyqttoast import Toast, ToastPreset
class Window(QMainWindow):
def __init__(self):
super().__init__(parent=None)
self.button = QPushButton(self)
self.button.setText('Show toast')
self.button.clicked.connect(self.show_toast)
def show_toast(self):
toast = Toast(self)
toast.setDuration(5000)
toast.setTitle('Success! Confirmation email sent.')
toast.setText('Check your email to complete signup.')
toast.applyPreset(ToastPreset.SUCCESS)
toast.show()
IMPORTANT:
An instance of Toast
can only be shown once. If you want to show another one, even if the content is exactly the same, you have to create another instance.
Customization
- Setting the position of the toasts (static):
Toast.setPosition(ToastPosition.BOTTOM_MIDDLE)
AVAILABLE POSITIONS:
BOTTOM_LEFT
, BOTTOM_MIDDLE
, BOTTOM_RIGHT
, TOP_LEFT
, TOP_MIDDLE
, TOP_RIGHT
, CENTER
- Setting whether the toasts should always be shown on the main screen (static):
Toast.setAlwaysOnMainScreen(True)
- Positioning the toasts relative to a widget instead of a screen (static):
Toast.setPositionRelativeToWidget(some_widget)
- Setting a limit on how many toasts can be shown at the same time (static):
Toast.setMaximumOnScreen(5)
If you try to show more toasts than the maximum amount on screen, they will get added to a queue and get shown as soon as one of the currently showing toasts is closed.
- Setting the vertical spacing between the toasts (static):
Toast.setSpacing(20)
- Setting the x and y offset of the toast position (static):
Toast.setOffset(30, 55)
- Making the toast show forever until it is closed:
toast.setDuration(0)
- Enabling or disabling the duration bar:
toast.setShowDurationBar(False)
toast.setIcon(ToastIcon.SUCCESS)
toast.setShowIcon(True)
toast.setIcon(QPixmap('path/to/your/icon.png'))
toast.setIconColor(None)
AVAILABLE ICONS:
SUCCESS
, WARNING
, ERROR
, INFORMATION
, CLOSE
toast.setIconSize(QSize(14, 14))
- Enabling or disabling the icon separator:
toast.setShowIconSeparator(False)
- Setting the close button alignment:
toast.setCloseButtonAlignment(ToastButtonAlignment.MIDDLE)
AVAILABLE ALIGNMENTS:
TOP
, MIDDLE
, BOTTOM
- Enabling or disabling the close button:
toast.setShowCloseButton(False)
- Customizing the duration of the fade animations (milliseconds):
toast.setFadeInDuration(100)
toast.setFadeOutDuration(150)
- Enabling or disabling duration reset on hover:
toast.setResetDurationOnHover(False)
- Making the corners rounded:
toast.setBorderRadius(3)
toast.setBackgroundColor(QColor('#292929'))
toast.setTitleColor(QColor('#FFFFFF'))
toast.setTextColor(QColor('#D0D0D0'))
toast.setDurationBarColor(QColor('#3E9141'))
toast.setIconColor(QColor('#3E9141'))
toast.setIconSeparatorColor(QColor('#585858'))
toast.setCloseButtonIconColor(QColor('#C9C9C9'))
font = QFont('Times', 10, QFont.Weight.Bold)
toast.setTitleFont(font)
toast.setTextFont(font)
toast.applyPreset(ToastPreset.ERROR)
AVAILABLE PRESETS:
SUCCESS
, WARNING
, ERROR
, INFORMATION
, SUCCESS_DARK
, WARNING_DARK
, ERROR_DARK
, INFORMATION_DARK
- Setting toast size constraints:
toast.setMinimumWidth(100)
toast.setMaximumWidth(350)
toast.setMinimumHeight(50)
toast.setMaximumHeight(120)
toast.setFixedSize(QSize(350, 80))
Other customization options:
Option | Description | Default |
---|
setFixedScreen() | Fixed screen where the toasts will be shown (static) | None |
setMovePositionWithWidget() | Whether the toasts should move with widget if positioned relative to a widget | True |
setIconSeparatorWidth() | Width of the icon separator that separates the icon and text section | 2 |
setCloseButtonIcon() | Icon of the close button | ToastIcon.CLOSE |
setCloseButtonIconSize() | Size of the close button icon | QSize(10, 10) |
setCloseButtonSize() | Size of the close button | QSize(24, 24) |
setStayOnTop() | Whether the toast stays on top of other windows even when they are focused | True |
setTextSectionSpacing() | Vertical spacing between the title and the text | 8 |
setMargins() | Margins around the whole toast content | QMargins(20, 18, 10, 18) |
setIconMargins() | Margins around the icon | QMargins(0, 0, 15, 0) |
setIconSectionMargins() | Margins around the icon section (the area with the icon and the icon separator) | QMargins(0, 0, 15, 0) |
setTextSectionMargins() | Margins around the text section (the area with the title and the text) | QMargins(0, 0, 15, 0) |
setCloseButtonMargins() | Margins around the close button | QMargins(0, -8, 0, -8) |
Demo
https://github.com/niklashenning/pyqt-toast/assets/58544929/f4d7f4a4-6d69-4087-ae19-da54b6da499d
The demos for PyQt5, PyQt6, and PySide6 can be found in the demo folder.
Tests
Installing the required test dependencies PyQt6, pytest, and coveragepy:
pip install PyQt6 pytest coverage
To run the tests with coverage, clone this repository, go into the main directory and run:
coverage run -m pytest
coverage report --ignore-errors -m
License
This software is licensed under the MIT license.