Skip to main content

Control how users clear or dismiss notifications

This article describes what removes a notification by default, and how to change that behavior:

Dismiss versus clear​

Dismissing a notification removes a toast and displays it only in Notification Center. Clearing a notification deletes it entirely from Notification Center.

info

You should be aware of the distinction especially if you set notifications without toasts (that is, only in Notification Center).

Default behavior​

In older versions of Notification Center, users clicked the body of a toast to dismiss it from the desktop. In Notifications v1.17.2 or later (HERE Core UI Components 9.1.22 or later), users click an 'x' in the upper right corner of the notification instead.

User actionDefault resultCan you change it?
Click the 'x' on a toastDismisses the toast.No.
Click the 'x' in Notification CenterClears the notification.No.
Click the notification bodyDoesn't dismiss the notification.Yes. See Let users dismiss by clicking the body.
Click a buttonRuns the button action and clears the notification entirely, including from Notification Center.Yes, in HERE Core UI Components 45.1 or later. See Keep a notification open after a button click.
Submit a formClears the notification entirely after successful submission, including from Notification Center.Yes, in HERE Core UI Components 45.1 or later. See Keep a notification open after a form submit.

Let users dismiss by clicking the body​

You can override the default behavior and allow the user to dismiss by clicking the body of the notification. Add the following to your notification create function:

const notification = {
  //...
  onSelect: { BODY_CLICK: ActionBodyClickType.DISMISS_EVENT },
};
info

In more recent versions of Notification Center, you can add actionable elements to the body of the notification. See Work with actionable fragments. If you add these elements to a notification, overriding the default dismiss behavior could create a confusing user experience.

See the Notifications API reference documentation for details.

Keep a notification open after a button click​

In HERE Core UI Components 45.1 or later, you can set persistOnClick on a button when the user needs to act more than once on the same notification, such as opening a reference and then choosing a call to action.

How it works​

persistOnClick is an optional boolean on ButtonOptions. The default is false. Set it to true on any primary (cta), secondary, or form submission button that should run its action and leave the notification open. Buttons on the same notification can use different values.

info

If a notification has more than one submit button (submit: true), all of them use the persistOnClick value of the first submit button. For example, if the first submit button has persistOnClick: false, the notification is cleared after a successful submit even when the user clicks a later submit button that has persistOnClick: true. Different values work as expected for ordinary buttons and for a single submit button.

The notification stays on the desktop toast and in Notification Center, and the usual notification events still fire so your application can handle the action. The same options work in HERE Core on the desktop, with @openfin/notifications, and in Notification Center in a web browser.

ActionpersistOnClick: truepersistOnClick omitted or false
Button clickThe action fires and the notification stays open.The action fires and the notification is cleared.
Form submitThe success label appears briefly, then the form is editable again and the notification stays open.The success label appears, then the notification is cleared.
Close (x)A toast is dismissed; in Notification Center, the notification is cleared.A toast is dismissed; in Notification Center, the notification is cleared.

What doesn't change​

  • The close button works as usual: it dismisses a toast, and it clears a notification in Notification Center.
  • Toast lifetime is unchanged: a transient toast still hides after the idle timeout, and a sticky toast still stays until the user dismisses it.

Example​

const notification = {
  title: "App Discovery",
  body: "New app available: Portfolio Analyzer",
  buttons: [
    {
      title: "Find out more",
      onClick: { action: "open-info" },
      persistOnClick: true,
    },
    {
      title: "Request Access",
      cta: true,
      onClick: { action: "request" },
    },
  ],
};

create(notification);

Find out more raises a notification-action event and leaves the notification open. Request Access raises its action and clears the notification.

See Buttons in a notification for onClick, cta, and other button properties.

Keep a notification open after a form submit​

In HERE Core UI Components 45.1 or later, you can use persistOnClick on a submit button, together with the clearForm() method of the form-submitted event, when the user needs to submit the same form more than once, such as logging several meeting notes on one notification. A submit button without persistOnClick keeps the existing behavior: the notification is cleared after a successful submit.

How it works​

  1. Give the submit button submit: true, cta: true, and persistOnClick: true. formOptions supplies the button text for the submitting and success states.

  2. In your notification-form-submitted listener, call preventDefault() and setFormStatus(), awaiting each status change.

  3. After you set the status to submitted, the button shows successTitle briefly, then the form returns to an editable state.

  4. Decide whether to reset the form:

    • Call clearForm() on the event to reset every field to its initial value.
    • Omit clearForm() when the user should see the values they just submitted.

clearForm() is available only on the submit event, so you call it from the handler after your own logic finishes, for example after a successful response from your application. For more about form fields, validation, and events, see Forms in notifications.

Clear the form after each submit​

Use this when the user adds a series of entries, such as meeting notes, on one notification.

create({
  title: "Meeting notes",
  body: "Add a note. The form clears after each save, and the notification stays open.",
  toast: "sticky",
  template: "markdown",
  form: [
    {
      key: "note",
      type: "string",
      label: "Note",
      widget: { type: "Text" },
    },
  ],
  buttons: [
    {
      title: "Add Note",
      submit: true,
      cta: true,
      persistOnClick: true,
      formOptions: {
        submittingTitle: "Saving...",
        successTitle: "Saved!",
      },
    },
  ],
});

addEventListener("notification-form-submitted", async (event) => {
  event.preventDefault();
  await event.setFormStatus({ formStatus: "submitting" });

  // Replace this delay with your application's save logic.
  await new Promise((resolve) => setTimeout(resolve, 500));

  await event.setFormStatus({ formStatus: "submitted" });
  await event.clearForm();
});

The user sees Saving..., then Saved!. The note field clears, and the notification stays open for the next entry.

Keep the values the user entered​

Omit clearForm() when the same values should remain editable, such as a draft the user may update again.

addEventListener("notification-form-submitted", async (event) => {
  event.preventDefault();
  await event.setFormStatus({ formStatus: "submitting" });
  await new Promise((resolve) => setTimeout(resolve, 500));
  await event.setFormStatus({ formStatus: "submitted" });
});

After Saved!, the form is editable again and the text the user typed is still there.

Table of Contents