<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 are appropriate when you want to inform the user about an event that is relevant to their ongoing use of an application. They are best used to provide immediate feedback. 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 not needed outside of the application window, and is immediately relevant. The button that allows the user to respond to the event, by pressing .</p>

<p>In-app notifications are not a good solution for communicating ongoing states. <link xref="info-bars">Info bars</link> offer one alternative you can consider.</p>

</section>

<section id="guidelies">
<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>