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 ------------------------- .. code-block:: python 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. .. code-block:: python 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: .. code-block:: python # 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: .. code-block:: python # 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: .. code-block:: python # 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: .. code-block:: python # 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: .. code-block:: python # 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 -------------------------------------------- .. code-block:: python # 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 -------------------------- .. code-block:: python 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: .. code-block:: python 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`. .. code-block:: python 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 :doc:`dclass documentation ` for more details. For more examples, please refer to the :doc:`API documentation `.