Usage

Rather than showing notifications immediately, you can queue them up and display them at the beginning of your app. This is useful if you want to rerun your app and notify users of a change after the rerun.

Supported Status Elements

import streamlit_notify as stn

# Use stn status widgets exactly as you would use a Streamlit status widget
stn.toast("This is a toast message", icon="✅")
stn.balloons()
stn.snow()
stn.success("Operation successful!")
stn.info("This is an info message")
stn.error("This is an error message")
stn.warning("This is a warning message")
stn.exception("This is an exception message")

Basic Usage

By default, displaying a notification will also clear it from its associated queue, but you can change this behavior by specifying remove=False to any notify function.

import streamlit as st
import streamlit_notify as stn

# Display all queued notifications at the beginning of your app (this will also clear the list)
stn.notify()

# To display notifications without clearing them, set remove=False
# stn.notify(remove=False)

# Queue a toast notification
if st.button("Show Toast"):
    stn.toast("This is a toast message", icon="✅")
    st.rerun()

# Queue a balloon notification
if st.button("Show Balloons"):
    stn.balloons()
    st.rerun()

# Queue a success notification
if st.button("Show Success Message"):
    stn.success("Operation successful!")
    st.rerun()

Notification Priority

You can set priorities for notifications, with higher priority notifications displayed first. Otherwise, notifications are displayed in the order they were added:

# Higher priority notifications are displayed first
stn.info("High priority message", priority=10)
stn.info("Low priority message", priority=-5)

for notification in stn.info.notifications:
    print(notification.priority)

Adding Custom Data to Notifications

You can attach custom data to notifications:

# Attach data to notifications
stn.info("Message with string data", data="Hello World")
stn.info("Message with dictionary data", data={'Hello': 'World'})

for notification in stn.info.notifications:
    print(notification.data)

Accessing Notifications

You can access notifications in different ways:

# Functional approach
all_notifications: list = stn.get_notifications()
error_notifications: list = stn.get_notifications('error')
toast_notifications: list = stn.get_notifications('toast')
toast_and_error_notifications: list = stn.get_notifications(['toast', 'error'])

# Or get them directly from each status element
error_notifications = stn.error.notifications.get_all()

Clearing Notifications

Clear notifications when you no longer need them:

# You can directly clear notifications from a specific status element
stn.error.notifications.clear()

# Clear all notifications
stn.clear_notifications()

# Or clear notifications of a specific type(s)
stn.clear_notifications('error')
stn.clear_notifications(['toast', 'error'])

Removing Notifications

You can remove notifications from the queue without displaying them:

# Remove a specific notification
stn.error.notifications.remove(notification)
stn.error.notifications.remove(1) # Remove by index

# Remove all notifications of a specific type
stn.error.notifications.remove_all()

# Or remove all notifications from the queue
stn.error.notifications.clear()

Checking if Notifications Exist in the Queue

# Check if any notifications exist
has_any_notifications = stn.has_notifications()
has_error_notifications = stn.has_notifications('error')
has_error_or_toast_notifications = stn.has_notifications(['error', 'toast'])

# Check by length
num_errors = len(stn.error.notifications)
num_errors = stn.error.notifications.size()

# Check if the error queue is empty
stn.error.notifications.is_empty()

# Or if the queue has any notifications
stn.error.notifications.has_items()

Looping Over Notifications

for notification in stn.error.notifications:
    # Optionally remove the notification from the queue
    # stn.error.notifications is a copy of the queue so we can modify it safely
    stn.error.notifications.remove(notification)

while not stn.error.notifications.is_empty():
    # Get and remove the first notification
    notification = stn.error.notifications.pop()

for notification in stn.get_notifications(['error', 'toast']):
    pass

Creating Notifications

You can create notifications without adding them to the queue, allowing you to control when they are displayed:

import streamlit_notify as stn

# Create a notification without adding it to the queue (must specify a notification_type)
notification = stn.create_notification("Info message", priority=5, notification_type="info")

# Create a notification with a specific type
notification = stn.info.create_notification("Info message", priority=5)

Where are Status Elements Stored?

The status elements are stored in a session state queue, under the key: ST_NOTIFY_{WIDGETNAME}_QUEUE.

import streamlit_notify as stn
import streamlit as st

sss_key = stn.success.session_state_key
print(sss_key) # Output: 'ST_NOTIFY_SUCCESS_QUEUE'

notifications = st.session_state[sss_key]

What are Status Elements?

Status elements are special notifications that are displayed in the Streamlit app, such as toasts, balloons, and success messages.

They are stored as a dataclass StatusElementNotification. Please refer to the dclass documentation for more details.

For more examples, please refer to the API documentation.