Documentation
Playground GitHub

$notify

Send a notification from a channel declared in src/notifications/.

A channel

A channel is a file. Its priority is in the name — @high, @default, @low, or @min:

// src/notifications/+Alerts@high.wh
@prop val title: String
@prop val body: String

<Notification title={title} body={body} />
  • +Alerts@high.wh — heads-up
  • +Messages@default.wh — default
  • +Updates@low.wh — no sound
  • +Background@min.wh — minimal

Sending one

$notify("/Alerts", "Warning", "Battery low")

The first argument is the channel's path, the way $navigate takes a route's path. $notify.cancelAll() clears every notification this app posted.

Actions

A channel can hold up to three buttons — Android's own limit — as children of <Notification>:

// src/notifications/+Messages@high.wh
@prop val title: String
@prop val body: String
@prop val senderId: String

<Notification
  title={title}
  body={body}
  onClick={() => $navigate("/chat/${senderId}")}
>
  <Button onClick={() => $navigate("/chat/${senderId}?reply=true")}>Reply</Button>
  <Button onClick={() => markAsRead(senderId)}>Mark read</Button>
</Notification>

Triggered the same way as any other channel:

$notify("/Messages", "New message", "Hey, how are you?")

Navigating on tap

onClick fires when the notification itself — not one of its buttons — is tapped:

<Notification
  title={title}
  body={body}
  onClick={() => $navigate("/detail/${itemId}")}
/>

Grouping

group and groupSummary let the system collapse related notifications into one line in the shade — several messages from the same conversation, several downloads at once:

<Notification title={title} body={body} group="downloads" />
<Notification title="3 downloads" groupSummary group="downloads" />
Users control channels in system settings, one at a time. A separate channel per kind of notification is what lets someone mute chat messages and keep download progress, or the reverse.

Declaring

Nothing to declare by hand. POST_NOTIFICATIONS is added to the manifest as soon as a channel exists, and the request happens through $permission("notifications") the same as any other runtime permission.

See Also