NotificationOptions

Configuration options for constructing a Notifications object.

Hierarchy

  • NotificationOptions

Index

Properties

body

body: string

Notification body text.

This is the main notification content, displayed below the notification title. The notification will expand to fit the length of this text. Markdown may be used in the body text to control how it is styled when rendered. With the exception of links and code blocks, all basic syntax as documented here is supported.

Optional buttons

buttons: ButtonOptions[]

A list of buttons to display below the notification text.

Notifications support up to four buttons. Attempting to add more than four will result in the notification being rejected by the service.

category

category: string

Describes the context of this notification. Allows users to control different notification types that are raised by an application.

This string is not displayed on the notification itself, but should be user-readable. It will be displayed in the Notification Center preferences section, and any string passed as a category should make sense when displayed in that context.

Event categories should list all the different types of notifications raised by your app. As a general guide, if a user may want to have different preferences for some subset of notifications created by your app, then applications should ensure that those notifications have a distinct category.

For example - given a calendar app, notification categories could be:

  • 'Upcoming Events': Notification that an event is about to start
  • 'Event Start': Notification raised when event starts, expiring at the event end time
  • 'Event Modified': When an event is modified
  • 'Event Cancelled': When an event is cancelled
  • 'Event Response': An attendee has responded to an event invitation that you created
  • 'Daily Agenda': A notification sent each morning with event reminders

NOTE: The user-facing UI that a user would use to manage their preferences is still in progress. This property has been added in advance of this UI being released, to ensure future compatibility.

Optional customData

customData: CustomData

Any custom context data associated with the notification.

When using forms, form data submitted will be written to customData and returned to your app by listening to the submit notification-action with the trigger submit.

Optional date

date: Date

The timestamp shown on the notification. If omitted, the current date/time will be used.

This is presentational only - a future date will not incur a scheduling action.

Optional expires

expires: Date | null

The expiry date and time of the notification. If specified, the notification will be removed at this time, or as soon as possible after. If not specified, the notification will never expire, and will persist until it is closed.

Optional form

Experimental

Add a form to a notification that users can input data into and submit back to your app. Each field within a form has a key unique property. For users to submit the form back to your app you should have a button with submit = true. Buttons with the submit property set to true will be disabled until a form is valid based on your validation rules set for each field.

When a form is submitted an notification-action event will be fired via the submit trigger. The {@link NotificationActionResult.result|result} will be the updated customData. See Actions for more details on notification actions, and receiving action events from notifications.

Optional icon

icon: undefined | string

URL of the icon to be displayed in the notification.

Optional id

id: undefined | string

A unique identifier for the notification.

If not provided at time of creation, one will be generated for you and returned as part of the create method.

Optional indicator

indicator: NotificationIndicator | null

Add a semantic visual indicator to a notification, to signal to the user the nature of the event that they are being notified about.

This should not be treated as a priority.

Optional onClose

onClose: ActionDeclaration<never, never> | null

An action result to be passed back to the application inside the notification-action event fired when the notification is closed.

This action will be raised regardless of how the notification is closed. This can be from user interaction (until future revisions allow default click behaviour to be overriden, this will be any click anywhere within the notification), the notification expiring, or from the notification being programmaticially removed, such as a call to clear.

See Actions for more details on notification actions, and receiving action events from notifications.

Optional onExpire

onExpire: ActionDeclaration<never, never> | null

An action result to be passed back to the application inside the notification-action event fired when the notification the expires.

If expires is specified for the notification, this action will be raised when the notification expires. If expires is not specified for the notification, this action will never be raised. Note that if an onClose action result is also specified, both actions will be raised if and when the notification expires.

See Actions for more details on notification actions, and receiving action events from notifications.

Optional onSelect

onSelect: ActionDeclaration<never, never> & ActionNoop | null

An action result to be passed back to the application inside the notification-action event fired when the notification is clicked.

This action will only be raised on clicks to the notification body. Interactions with buttons (both application-defined buttons, and the default 'X' close button) will not trigger a select action.

See Actions for more details on notification actions, and receiving action events from notifications.

Optional sticky

sticky: "sticky" | "transient"

When set to sticky this settings enables the notification toast to stay visible on the desktop until the user interacts with it. When set to transient the toasts will follow the default behavior of fading away after a short duration

The default value is transient.

title

title: string

Title of the notification.

Displayed as the first line of the notification, in a heading style.