PyQtToast Notification Library

To show a toast, import the Toast class, instantiate it (passing a parent widget), configure its properties, and call .show().

Important: An instance of Toast can only be shown once. To show another notification, you must create a new instance of Toast.

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)  # Hide after 5 seconds
        toast.setTitle('Success! Confirmation email sent.')
        toast.setText('Check your email to complete signup.')
        toast.applyPreset(ToastPreset.SUCCESS)  # Apply style preset
        toast.show()

Configure specific visual elements for a single Toast instance:

Icons

• toast.setShowIcon(True): Enables the icon. (Default: False)
• toast.setIcon(ToastIcon.ICON_TYPE): Sets a preset icon. Available: SUCCESS, WARNING, ERROR, INFORMATION, CLOSE. (Default: INFORMATION)
• toast.setIcon(QPixmap('path/to/icon.png')): Sets a custom image icon.
• toast.setIconColor(QColor): Sets the icon color. Set to None to show the icon without recoloring it. (Default: #5C5C5C)
• toast.setIconSize(QSize(w, h)): Sets the icon size. (Default: QSize(18, 18))
• toast.setShowIconSeparator(bool): Enables/disables the separator between icon and text. (Default: True)
• toast.setIconSeparatorWidth(int): Width of the icon separator. (Default: 2)

Close Button

• toast.setShowCloseButton(bool): Enables/disables the close button. (Default: True)
• toast.setCloseButtonAlignment(ToastButtonAlignment.ALIGNMENT): Sets alignment. Available: TOP, MIDDLE, BOTTOM. (Default: TOP)
• toast.setCloseButtonIcon(ToastIcon.ICON_TYPE): Sets the close button icon. (Default: ToastIcon.CLOSE)
• toast.setCloseButtonIconSize(QSize): Size of the close button icon. (Default: QSize(10, 10))
• toast.setCloseButtonSize(QSize): Size of the close button. (Default: QSize(24, 24))

Animations and Interaction

• toast.setDuration(int): Duration in ms. Set to 0 to show forever. (Default: 5000)
• toast.setShowDurationBar(bool): Enables/disables the duration bar. (Default: True)
• toast.setFadeInDuration(int) / toast.setFadeOutDuration(int): Animation duration in ms. (Default: 250)
• toast.setResetDurationOnHover(bool): Whether duration resets when hovering. (Default: True)
• toast.setStayOnTop(bool): Whether toast stays on top of other windows. (Default: True)
• toast.setMovePositionWithWidget(bool): If true, toasts move with the widget they are relative to. (Default: True)

The following methods are static and configure how all toasts behave globally within the application:

• Toast.setPosition(ToastPosition.POSITION): Sets the static position. Available: BOTTOM_LEFT, BOTTOM_MIDDLE, BOTTOM_RIGHT, TOP_LEFT, TOP_MIDDLE, TOP_RIGHT, CENTER. (Default: BOTTOM_RIGHT)
• Toast.setAlwaysOnMainScreen(True): Forces toasts to always show on the main screen. (Default: False)
• Toast.setPositionRelativeToWidget(some_widget): Positions toasts relative to a specific widget instead of the screen. (Default: None)
• Toast.setMaximumOnScreen(int): Limits the number of toasts visible at once. Excess toasts are queued. (Default: 3)
• Toast.setSpacing(int): Sets vertical spacing between toasts. (Default: 10)
• Toast.setOffset(x, y): Sets the x and y offset of the toast position. (Default: 20, 45)
• Toast.setFixedScreen(screen): Sets a fixed screen where toasts will be shown.

Use QColor and QFont to fully brand your notifications.

Colors

• toast.setBackgroundColor(QColor): (Default: #E7F4F9)
• toast.setTitleColor(QColor): (Default: #000000)
• toast.setTextColor(QColor): (Default: #5C5C5C)
• toast.setDurationBarColor(QColor): (Default: #5C5C5C)
• toast.setIconColor(QColor): (Default: #5C5C5C)
• toast.setIconSeparatorColor(QColor): (Default: #D9D9D9)
• toast.setCloseButtonIconColor(QColor): (Default: #000000)

Fonts

• toast.setTitleFont(QFont): (Default: Arial, 9, Bold)
• toast.setTextFont(QFont): (Default: Arial, 9)

Layout and Sizing

• toast.setBorderRadius(int): Makes corners rounded. (Default: 0)
• toast.setMinimumWidth(int) / toast.setMaximumWidth(int)
• toast.setMinimumHeight(int) / toast.setMaximumHeight(int)
• toast.setFixedSize(QSize): Sets a fixed size (not recommended).
• toast.setTextSectionSpacing(int): Vertical spacing between title and text. (Default: 8)
• toast.setMargins(QMargins): Margins around the whole content. (Default: QMargins(20, 18, 10, 18))
• toast.setIconMargins(QMargins): Margins around the icon.
• toast.setIconSectionMargins(QMargins): Margins around the icon and separator area.
• toast.setTextSectionMargins(QMargins): Margins around the title and text area.
• toast.setCloseButtonMargins(QMargins): Margins around the close button.

The Toast class is the primary interface for displaying notification dialogs in PyQt applications. It inherits from QDialog and manages its own lifecycle, including animations (fade in/out), positioning on screen, and a queue system to ensure no more than a specified number of notifications are visible at once.

Key behaviors:

• Automatic Queuing: If the maximum number of toasts on screen is reached, new toasts are queued and shown automatically as previous ones close.
• Animations: Supports fade-in/out opacity effects and position animations when new toasts appear.
• Hover Behavior: By default, hovering over a toast resets its duration timer and the duration bar animation, preventing the notification from disappearing while the user is reading it.
• Positioning: Can be positioned relative to a specific widget or on a specific screen.

from pyqttoast.toast import Toast

# Basic instantiation
toast = Toast(parent=my_widget)
toast.setTitle("Success")
toast.setText("Operation completed successfully!")
toast.show()