xmlns:uix="http://projectmallard.org/experimental/ui/"

      type="topic"

      id="empty-placeholder">

  <info>

    <link type="guide" xref="patterns#secondary"/>

    <desc>Image and text shown when a grid or list is empty</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>Empty placeholders</title>

<media type="image" mime="image/svg" src="figures/patterns/empty-placeholder.svg"/>

An empty placeholder is an image and text which fills the space in an empty list or grid.

<section id="when-to-use">

<title>When to use</title>

Empty placeholders perform a number of important functions: they prevent confusion and guide the user, and they make your interface look better and more cohesive. They are also one of those nice touches which helps to communicate an attention to detail.

An empty placeholder should be displayed whenever a list or grid is empty.

Empty placeholders should not be displayed when an application is being run for the first time. In these situations an empty state is too negative and <link xref="initial-state-placeholder">a richer, more characterful and positive experience</link> is better.

</section>

<section id="guidelines">

<title>Guidelines</title>

<list>

<item>
Follow the standard layout for the size and placement of the image and labels, so that your application is consistent with other GNOME 3 applications.
</item>

<item>
For the image, use a <link xref="icons-and-artwork#color-vs-symbolic">symbolic icon</link> that either represents your application, or the type of content that would ordinarily appear in the grid or list.
</item>

<item>
An empty placeholder should always include a label which communicates the empty state. It is often appropriate to include a smaller subtext which provides additional guidance (such as how to add items). However, this should only be included if there is additional information that it is useful to provide.
</item>

<item>
If there are controls that allow items to be added, it can be appropriate to highlight them using a <link xref="buttons#suggested-and-destructive">suggested style</link> while the list/grid is empty.
</item>

</list>

</section>

</page>