The page navigation is complete. You may now navigate the page content as you wish.
Skip to main content

Application State

Figma GitHub

An informational element that displays the current state of the application.

The Application State is used to communicate status, errors, and zero/empty states.

Usage

When to use

  • When an application encounters an issue or error during its operation.
  • When emphasis is needed on the creation of a new object within a null state.

When not to use

  • When the absence of content is expected and does not require an explanation to the user.
  • When there is a clear and intuitive way to add or populate content.

Alignment

The Application State supports two alignment options: left (default) and center. The alignment affects text alignment, action placement/alignment in the footer, and media placement; however, it does not change the default page alignment.

By default, the Application State has horizontal auto margins applied to it, always centering it on the page or containing element. This can be overridden with CSS properties.

Left alignment

Left aligned application state

Center alignment

Center aligned application state

Media

The media slot is used to add illustrations to increase the visual impact of the Application State.

This provides additional visual prominence while also elevating the brand experience. If the illustration has a circular container, we recommend setting the alignment to center.

Empty state for Vault Secrets, guiding user to create new secrets or importing them

Icon

When set, the icon is displayed side by side with the title.

Showing an icon left of the title, with some body text below it.

This is commonly used when displaying an error state for application failures. The icon must always be accompanied by a title.

Title

The title should be short and provide a clear and concise message.

Error code

If enabled and available, an error code will be shown, providing additional information associated with the title.

Body

Focus on relevant information and avoid unnecessary details. If there is an error, include suggestions or guidance for how the user can resolve the issue, if possible. If no objects are found (zero/empty state), provide a brief explanation on how creating this new object will benefit the user.

The body allows for two types of content: text and generic.

Showing two different kind of body content types, one as text and another as generic yielded content

The Application State supports up to three actions, including Dropdown, Standalone Link, and Button components. Use footer actions to help users resolve errors or access issues with actionable steps.

A button set showing a dropdown, secondary button, and stand alone link

Buttons, along with links, are the most common actions used in the footer. Buttons are more often used in empty state contexts because they provide high visibility for the primary action on the page. Links are more common in error state contexts as a means to provide a solution to the error they encountered.

Read more about when to use Buttons and Links.

Don’t

When there is an empty state that occupies the majority of the page, do not display two similar actions in different areas of the UI. In this example, there is a primary button in the Page Header and in the Application State.

Showing an empty state with a primary button and a page header with a primary button

Do

Instead, use the Application State as the only means of drawing attention to the primary action.

Showing an empty state with a primary button with a page header with out a primary button

Using dropdowns

Dropdowns can be used as actions in the footer in rare cases. Limit dropdowns to one per Application State.

Showing an empty state with a primary button with a page header with out one

Width constraints

The Application State’s content has a max width of 480 pixels. This is done for better readability, ensuring that the max character count is close to 70 characters per line.

Examples

Here are some common use cases for the Application State, however, it is not limited to just these two examples.

Error state

Error states are used when the application encounters an issue or error during its operation. It shows the associated error code, icon, messages, and actions to help users find a solution.

Showing an example of an error state with a 404 error code and two links

Empty state

An empty state occurs when a user has yet to create an object. Illustrations are placed using the media slot to further elevate the experience and express the purpose of the object.

Showing an empty state with a primary and secondary button along with a stand alone link

How to use this component

This component intends to replace a few different simple error and empty/zero state components that exist across product UIs, while providing flexibility to adapt to additional application states. While we’re referring to these as "error state" and "empty state" this is just to help consumers relate to the components that have been replaced. Really, this component can be used to reflect any kind of application state message that is needed.

As an empty state

Empty state title text

The item you were looking for was not found. 

<Hds::ApplicationState as |A|>
  <A.Header @title="Empty state title text" />
  <A.Body @text="The item you were looking for was not found." />
</Hds::ApplicationState>

Empty state with header icon

Empty state title text

The item you were looking for was not found. 

<Hds::ApplicationState as |A|>
  <A.Header @title="Empty state title text" @icon="alert-circle" />
  <A.Body @text="The item you were looking for was not found." />
</Hds::ApplicationState>
Empty state title text

The item you were looking for was not found.

Need Help 
<Hds::ApplicationState as |A|>
  <A.Header @title="Empty state title text" />
  <A.Body @text="The item you were looking for was not found." />
  <A.Footer as |F|>
    <F.LinkStandalone @icon="help" @text="Need Help" @href="/components/alert"
    @iconPosition="trailing" />
  </A.Footer>
</Hds::ApplicationState>

Empty state with yielded body block

Empty state title text
block yield
Go back 
<Hds::ApplicationState as |A|>
  <A.Header @title="Empty state title text" />
  <A.Body>
    <Doc::Placeholder @text="block yield" @height="100" @background="#eee" />
  </A.Body>
  <A.Footer as |F|>
    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
  </A.Footer>
</Hds::ApplicationState>

Empty state with body text

Empty state title text

Some sentence that conveys a good message to the user

Go back 
<Hds::ApplicationState as |A|>
  <A.Header @title="Empty state title text" />
  <A.Body @text="Some sentence that conveys a good message to the user" />
  <A.Footer as |F|>
    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
  </A.Footer>
</Hds::ApplicationState>

Empty state with center alignment

Empty state title text

Some sentence that conveys a good message to the user

Go back 
<Hds::ApplicationState @align="center" as |A|>
  <A.Header @title="Empty state title text" />
  <A.Body @text="Some sentence that conveys a good message to the user" />
  <A.Footer as |F|>
    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
  </A.Footer>
</Hds::ApplicationState>

Empty state with media

portrait of a cat wearing coat and tie
Empty state title text

Some sentence that conveys a good message to the user

Go back 
<Hds::ApplicationState as |A|>
  <A.Media><img src="/assets/images/avatar-bd9ab58aeb803d6e0c0001377034d99d.png" alt="portrait of a cat wearing coat and tie" /></A.Media>
  <A.Header @title="Empty state title text" />
  <A.Body @text="Some sentence that conveys a good message to the user" />
  <A.Footer as |F|>
    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
  </A.Footer>
</Hds::ApplicationState>

As an error state

To indicate that the message is an error state, add @errorCode to the [A].Header component invocation.

ERROR 404
An error has occurred

Sorry, an unexpected error has occurred. Please try again later or contact support for assistance.

Go back Need Help 
<Hds::ApplicationState as |A|>
  <A.Header @title="An error has occurred" @errorCode="404" />
  <A.Body
    @text="Sorry, an unexpected error has occurred.
    Please try again later or contact support for assistance."
  />
  <A.Footer as |F|>
    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
    <F.LinkStandalone @icon="help" @text="Need Help" @href="/components/alert" 
      @iconPosition="trailing" />
  </A.Footer>
</Hds::ApplicationState>

Error state with header icon

ERROR 404
An error has occurred

Sorry, an unexpected error has occurred. Please try again later or contact support for assistance.

Go back Need Help 
<Hds::ApplicationState as |A|>
  <A.Header @title="An error has occurred" @icon="help" @errorCode="404" />
  <A.Body
    @text="Sorry, an unexpected error has occurred.
    Please try again later or contact support for assistance."
  />
  <A.Footer as |F|>
    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
    <F.LinkStandalone @icon="help" @text="Need Help" @href="/components/alert" 
      @iconPosition="trailing" />
  </A.Footer>
</Hds::ApplicationState>

Error state with yielded body block

ERROR 404
An error has occurred
block yield
Go back Need Help 
<Hds::ApplicationState as |A|>
  <A.Header @title="An error has occurred" @errorCode="404" />
  <A.Body>
    <Doc::Placeholder @text="block yield" @height="100" @background="#eee" />
  </A.Body>
  <A.Footer as |F|>
    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
    <F.LinkStandalone @icon="help" @text="Need Help" 
      @href="/components/alert" @iconPosition="trailing" />
  </A.Footer>
</Hds::ApplicationState>

Error state with center alignment

ERROR 404
An error has occurred

Sorry, an unexpected error has occurred. Please try again later or contact support for assistance.

Go back Need Help 
<Hds::ApplicationState @align="center" as |A|>
  <A.Header @title="An error has occurred" @errorCode="404" />
  <A.Body
    @text="Sorry, an unexpected error has occurred.
    Please try again later or contact support for assistance."
  />
  <A.Footer as |F|>
    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
    <F.LinkStandalone @icon="help" @text="Need Help" 
      @href="/components/alert" @iconPosition="trailing" />
  </A.Footer>
</Hds::ApplicationState>

Error state with media

portrait of a cat wearing coat and tie
ERROR 404
An error has occurred

Sorry, an unexpected error has occurred. Please try again later or contact support for assistance.

Go back Need Help 
<Hds::ApplicationState as |A|>
  <A.Media><img src="/assets/images/avatar-bd9ab58aeb803d6e0c0001377034d99d.png" alt="portrait of a cat wearing coat and tie" /></A.Media>
  <A.Header @title="An error has occurred" @errorCode="404" />
  <A.Body
    @text="Sorry, an unexpected error has occurred.
    Please try again later or contact support for assistance."
  />
  <A.Footer as |F|>
    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
    <F.LinkStandalone @icon="help" @text="Need Help" 
      @href="/components/alert" @iconPosition="trailing" />
  </A.Footer>
</Hds::ApplicationState>

Title tag

The @titleTag argument changes the HTML element that wraps the [A].Header title content. When organizing the content on a webpage, the heading levels should reflect the structure of the page. For example, if an Application State is used as an empty state below the main heading of a page, the value should be "h2".

Templates

No templates have been created yet

Make a template to easily provision infrastructure for any Waypoint application. You’ll need a Terraform co-node module and instructions for your application developers.

Learn more 
<div class="doc-application-state-demo-heading">
  <Hds::Text::Display @tag="h1" @size="500">Templates</Hds::Text::Display>
</div>
<Hds::ApplicationState as |A|>
  <A.Header @title="No templates have been created yet" @titleTag="h2" />
  <A.Body @text="Make a template to easily provision infrastructure for any Waypoint application. You’ll need a Terraform co-node module and instructions for your application developers." />
  <A.Footer as |F|>
    <F.Button @icon="plus" @text="Create a template" />
    <F.Button @icon="upload" @text="Import" @color="secondary" />
    <F.LinkStandalone @icon="docs-link" @text="Learn more" @href="/components/application-state"
    @iconPosition="trailing" />
  </A.Footer>
</Hds::ApplicationState>

The default @titleTag is "div" because the correct value is dependent on the individual page. We strongly encourage consumers to update the @titleTag to meet WCAG Success Criterion 1.3.1 Info and Relationships as the visual experience should match what is presented to the user with assistive technology.

Component API

ApplicationState

align enum
  • left (default)
  • center
Sets the alignment of the Application State content.
<[A].Media> yielded component
ApplicationState::Media yielded as contextual component (see below).
<[A].Header> yielded component
ApplicationState::Header yielded as contextual component (see below).
<[A].Body> yielded component
ApplicationState::Body yielded as contextual component (see below).
<[A].Footer> yielded component
ApplicationState::Footer yielded as contextual component (see below).
…attributes
This component supports use of ...attributes.

Contextual components

[A].Media

The ApplicationState::Media component, yielded as contextual component.

yield
Elements passed as children are yielded as inner content of the "media" block.
…attributes
This component supports use of ...attributes.

[A].Header

The ApplicationState::Header component, yielded as contextual component.

errorCode string
The error code to be displayed.
icon string
Adds a leading icon to the title. Accepts any icon name.
title string
The text of the title
titleTag enum
  • div (default)
  • h1
  • h2
  • h3
  • h4
  • h5
  • h6
The HTML tag that wraps the title text.
…attributes
This component supports use of ...attributes.

[A].Body

The ApplicationState::Body component, yielded as contextual component.

yield
Elements passed as children are yielded as inner content of the "body" block.
text string
Note: use @text to pass directly text to the "body", with a predefined style. This component does not support @text on the component invocation if it is used with yielded content.
…attributes
This component supports use of ...attributes.

[A].Footer

The ApplicationState::Footer component, yielded as contextual component.

<[F].Button> yielded component
The Button component, yielded as contextual component inside the "footer" block of the ApplicationState. It exposes the same API as the Button component.
<[F].Dropdown> yielded component
The Dropdown component, yielded as contextual component inside the "footer" block of the ApplicationState. It exposes the same API as the Dropdown component.
<[F].LinkStandalone> yielded component
The Link::Standalone component, yielded as contextual component inside the "footer" block of the ApplicationState. It exposes the same API as the Link::Standalone component.
…attributes
This component supports use of ...attributes.

Anatomy

Anatomy of the application-state component

Element Usage
Media Optional.
Title Required.
Icon Optional, but recommended with errorCode.
errorCode Optional, but recommended when in errorState.
Body Required.
Footer Optional.
Actions Required, if no footer; optional.

Conformance rating

Conformant

When used as directed, there should not be any conformance issues with this component. Consumers are responsible for the conformance of any content in a block yield.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

  • 1.1.1 Non-text Content (Level A):
    All non-text content that is presented to the user has a text alternative that serves the equivalent purpose.
  • 1.3.1 Info and Relationships (Level A):
    Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
  • 1.3.2 Meaningful Sequence (Level A):
    When the sequence in which content is presented affects its meaning, a correct reading sequence can be programmatically determined.
  • 1.4.1 Use of Color (Level A):
    Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.
  • 1.4.10 Reflow (Level AA):
    Content can be presented without loss of information or functionality, and without requiring scrolling in two dimensions.
  • 1.4.11 Non-text Contrast (Level AA):
    The visual presentation of the following have a contrast ratio of at least 3:1 against adjacent color(s): user interface components; graphical objects.
  • 1.4.12 Text Spacing (Level AA):
    No loss of content or functionality occurs by setting all of the following and by changing no other style property: line height set to 1.5; spacing following paragraphs set to at least 2x the font size; letter-spacing set at least 0.12x of the font size, word spacing set to at least 0.16 times the font size.
  • 1.4.3 Minimum Contrast (Level AA):
    The visual presentation of text and images of text has a contrast ratio of at least 4.5:1
  • 1.4.4 Resize Text (Level AA):
    Except for captions and images of text, text can be resized without assistive technology up to 200 percent without loss of content or functionality.
  • 2.1.1 Keyboard (Level A):
    All functionality of the content is operable through a keyboard interface.
  • 2.1.2 No Keyboard Trap (Level A):
    If keyboard focus can be moved to a component of the page using a keyboard interface, then focus can be moved away from that component using only a keyboard interface.
  • 2.4.4 Link Purpose In Context (Level A):
    The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general.
  • 2.4.6 Headings and Labels (Level AA):
    Headings and labels describe topic or purpose.
  • 2.4.7 Focus Visible (Level AA):
    Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible.
  • 3.2.1 On Focus (Level A):
    When any user interface component receives focus, it does not initiate a change of context.
  • 3.3.3 Error Suggestion (Level AA):
    If an input error is automatically detected and suggestions for correction are known, then the suggestions are provided to the user, unless it would jeopardize the security or purpose of the content.
  • 4.1.2 Name, Role, Value (Level A):
    For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.
  • 4.1.3 Status Messages (Level AA):
    In content implemented using markup languages, status messages can be programmatically determined through role or properties such that they can be presented to the user by assistive technologies without receiving focus.

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

4.10.0

Updated

Updated the type of the @titleTag argument to only accept "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6". If using another value, update the argument to the appropriate heading level. For example, if an Application State is used as an empty state below the main heading of a page, the value should be "h2".

4.8.0

Updated

ApplicationState

  • Added new @align argument for aligning content (left (default) and center)
  • Added new yielded Media child component to support illustrations
  • Visual updates related to text colors, spacing and alignment

ApplicationState::Header

  • The header now supports an optional @titleTag argument that can override the default title element (div)

ApplicationState::Footer

  • The footer now yields also Button and Dropdown components to be used as actions
  • The visual separator has been removed to modernize the component’s visual look

On this page: