<page xmlns="http://projectmallard.org/1.0/"
      xmlns:uix="http://projectmallard.org/experimental/ui/"
      type="topic"
      id="in-app-notifications">

  <info>
    <link type="guide" xref="patterns#primary"/>
    <desc>Application event notifications</desc>
    <credit type="author">
      <name>Allan Day</name>
      <email>aday@gnome.org</email>
    </credit>
    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  </info>

<title>In-app notifications</title>

<media type="image" mime="image/svg" src="figures/patterns/in-app-notification.svg"/>

<p>In-app notifications are information popups which can be displayed inside an application. They include a label which describes an event that has happened, and can also include a button that allows the user to respond. They are always transient and user dismissable.</p>

<section id="when-to-use">
<title>When to use</title>

<p>In-app notifications can be used to inform users about events that are immediately relevant to their activity in an application, but which don't have long-term interest. One common use is to provide feedback in response to user actions, while the application is being used. This contrasts with <link xref="notifications">standard notifications</link>, which provide system-wide alerts, and which persist after the notification has been initially displayed.</p>

<p>Allowing the user to undo a destructive action is an example of a good use of in-app notifications: the notification is shown immediately after a user action, and is shown in the most relevant context.</p>

<p>In-app notifications are not a good solution for communicating ongoing states.</p>

</section>

<section id="guidelines">
<title>Guidelines</title>

<list>
<item><p>It isn't always necessary to include an action button in an in-app notification: only include one if it is directly related to the event and is generally useful.</p></item>
<item><p>Don't distract with unnecessary in-app notifications, and be careful not to overuse them: they can be annoying if they pop up frequently.</p></item>
<item><p>Only one in-app notification can be displayed at a time, and new instances should replace existing ones.</p></item>
</list>

</section>

</page>
