Overview

Introduction

Notifications are short, typed messages built with a fluent Notification API. Calling .send() flashes them into the panel toast host (Alpine orbitNotifications). The same object can also persist to the database bell or broadcast live.

Use them after a save, when a background job finishes, or anywhere you want a non-blocking “it worked / look at this” cue without navigating away.

from almasix.orbit.notifications import Notification

Notification.make()
    .title("Saved successfully")
    .success()
    .send()

Orbit Notifications overview (light)

Orbit Notifications overview (dark)

The panel shell renders a toast host when notifications are enabled (default). Pair with action .success_notification("Saved") so CRUD flows feel finished — see Actions.

Setting a title

The main message is the title. Pass it via .title(...), or use Notification.make(title="…").

To give the toast a stable id you can close later, pass a single word (no spaces) as the first argument: Notification.make("greeting"). Otherwise Orbit assigns a random id.

from almasix.orbit.notifications import Notification

Notification.make()
    .title("Saved successfully")
    .send()

Orbit Notification title (light)

Orbit Notification title (dark)

Or from JavaScript with OrbitNotification:

new OrbitNotification()
  .title("Saved successfully")
  .send();

Setting an icon

Optionally show a Heroicon in front of the content. .icon_color(...) tints the icon (defaults follow status when you use .success() and friends).

from almasix.orbit.notifications import Notification

Notification.make()
    .title("Saved successfully")
    .icon("heroicon-o-document-text")
    .icon_color("success")
    .send()

new OrbitNotification()
  .title("Saved successfully")
  .icon("heroicon-o-document-text")
  .iconColor("success")
  .send();

Status helpers

Notifications often carry a status — success, warning, danger, or info. Prefer .success() / .warning() / .danger() / .info() (or .status(...)). Status sets a default icon and colors unless you already called .icon(...) / .color(...).

from almasix.orbit.notifications import Notification

Notification.make()
    .title("Saved successfully")
    .success()
    .send()

Orbit Notification status (light)

Orbit Notification status (dark)

new OrbitNotification()
  .title("Saved successfully")
  .success()
  .send();

Setting a background color

Use .color(...) for extra context on the toast chrome (success, warning, danger, info, …). Status helpers set color automatically when unset.

from almasix.orbit.notifications import Notification

Notification.make()
    .title("Saved successfully")
    .color("success")
    .send()

Orbit Notification color (light)

Orbit Notification color (dark)

Setting a duration

By default toasts close after 6 seconds. Override with .duration(ms) or .seconds(n).

from almasix.orbit.notifications import Notification

Notification.make()
    .title("Saved successfully")
    .success()
    .duration(5000)
    .send()

Notification.make()
    .title("Saved successfully")
    .success()
    .seconds(5)
    .send()

Orbit Notification duration (light)

Orbit Notification duration (dark)

Persistent toasts

.persistent() keeps the toast until the user dismisses it (no auto-close).

from almasix.orbit.notifications import Notification

Notification.make()
    .title("Review required")
    .warning()
    .persistent()
    .send()

Orbit Notification persistent (light)

Orbit Notification persistent (dark)

new OrbitNotification()
  .title("Review required")
  .warning()
  .persistent()
  .send();

Setting body text

.body(...) adds a secondary line under the title (body_text is a legacy alias).

from almasix.orbit.notifications import Notification

Notification.make()
    .title("Saved successfully")
    .success()
    .body("Changes to the post have been saved.")
    .send()

Orbit Notification body (light)

Orbit Notification body (dark)

Adding actions

Footer buttons use NotificationAction. They can open a URL, dispatch a browser event, close the toast, or mark database rows read/unread.

from almasix.orbit.notifications import Notification, NotificationAction

Notification.make()
    .title("Saved successfully")
    .success()
    .body("Changes to the post have been saved.")
    .actions([
        NotificationAction.make("view")
            .button()
            .url("/admin/posts/1", should_open_in_new_tab=True),
        NotificationAction.make("undo")
            .color("gray")
            .dispatch("undoEditingPost", [1])
            .close(),
    ])
    .send()

Orbit Notification actions (light)

Orbit Notification actions (dark)

new OrbitNotification()
  .title("Saved successfully")
  .success()
  .body("Changes to the post have been saved.")
  .actions([
    new OrbitNotificationAction("view").button().url("/view").openUrlInNewTab(),
    new OrbitNotificationAction("undo").color("gray").dispatch("undoEditingPost").close(),
  ])
  .send();

Method	Notes
`.button`	Render as a compact button
`.url`	Link target; `should_open_in_new_tab` / `.open_url_in_new_tab`
`.dispatch` / `.dispatch_self` / `.dispatch_to`	Browser / component events + payload
`.close`	Dismiss the toast after the action
`.color`	Action chrome color
`.mark_as_read` / `.mark_as_unread`	Database bell helpers

Sending notifications

.send() uses the flash channel and the context-local Notifier (process default when unset). Prefer calling it from actions, services, or after mutations — the next panel render (or the JS client) shows the toast.

from almasix.orbit.notifications import Notification, get_notifier

Notification.make().title("Hello").info().send()

# Tests / request scope
notifier = get_notifier()
assert notifier.peek_flash()

Testing helpers: assert_notified, assert_not_notified, reset_notifications from almasix.orbit.notifications.

Using the JavaScript objects

Published orbit.js assigns window.OrbitNotification and window.OrbitNotificationAction. They dispatch orbit:notify for the Alpine toast host.

new OrbitNotification()
  .title("Saved successfully")
  .success()
  .body("Changes to the post have been saved.")
  .send();

Action buttons can also toast without Python via data-success-notification / data-failure-notification (set by .success_notification(...) / .failure_notification(...)).

Closing a notification by id

After .send(), call .get_id() (Python) or .getId() (JS). Dispatch close-notification with that id, or pass a custom id when creating the notification.

from almasix.orbit.notifications import Notification

note = (
    Notification.make("greeting")
    .title("Hello")
    .persistent()
    .send()
)
# Close later: dispatch close-notification with id "greeting"

<button
  type="button"
  x-on:click="$dispatch('close-notification', { id: 'greeting' })"
>
  Close
</button>

Random ids are safer when you can persist them; reuse a custom id only when you intend to replace/close that toast.

Positioning notifications

Configure toast alignment process-wide (provider / middleware) with Notifications.alignment and Notifications.vertical_alignment. Values: start / center / end for both axes (defaults: end + start).

from almasix.orbit.notifications import Alignment, Notifications, VerticalAlignment

Notifications.alignment(Alignment.START)
Notifications.vertical_alignment(VerticalAlignment.END)

Orbit Notification alignment (light)

Orbit Notification alignment (dark)