Empty State

Anatomy

1. Illustration: A visual representation of the situation.
2. Title: A concise explanation of the situation.
3. Message (Optional): Supporting information and/or a suggestion to take a first action or fix the error.
4. Primary Action (Optional): The suggested action to take a first action or resolve an error.
5. ** Secondary Action (Optional):** Generally represents an exit or way back. This may be omitted for required software updates or in cases where there is no content as this is a first usage.

Usage Guidance

When to Use

• When navigating to a task for the first time and no content displays because it needs to be added or created first.
• When navigating to a page that fails to load, whether due to server or connectivity issues.
• When navigating to a page that a user doesn’t have security access to.
• When an app update is required or recommended in order to view app content.

When to Consider Something Else

• In the case of an error, if part of the page content can be loaded, use a Banner to indicate an error instead.
• To display input level error validation, use a Banner.
• If an element or link will never be available to users, consider hiding the element rather than routing users to an error Empty State.
• If error information is critical and requires user action or decision, consider using an Alert Dialog. Alert Dialogs are reserved for messages of the highest priority; they command user action by blocking any other interactions.
• If communicating updates about the progress of an application, consider using Snackbars; they do not require user action.

Behaviors

Page Loading

In error use cases, page loading animations persist until page load failure, then a full page error appears. The error remains until the user exits the app, navigates back to the previous page, or taps the primary action button.

In other Empty State use cases, the page loading animations persist until the page loads, then the full page Empty State displays.

Both failed page loading and Empty States use a 150ms fade-in of the full-page error, replacing the existing loading indicator.

Actions

Onboarding / First Time Use

Empty States are a pivotal point in the user journey. They are opportunities to build rapport, drive engagement, educate, or delight the user. Empty States should never actually feel empty.

Onboarding or first time Empty States generally display a primary action only. This primary action should try to offer a logical first step (“Create a Document” “Start a Referral”). See examples in the Empty State Figma spec.

Errors

Error Empty States generally display a primary and secondary option. The primary action should provide a remedy for the error (“Refresh,” “Continue to Browser”). The secondary action should offer a way out (“Go Back”). Where no remedy is available, use “Go Back” as the primary action.

If “Refresh” is an option, once “Refresh Page” is tapped, the page should attempt to reload or refresh. If the error persists then the Full Page Error should reappear. If the error is resolved the normal content should appear for that page.

Longer Empty State Messages

In general, Empty State messages should be concise. Follow the content recommendations in Error and Alert Messages and Empty States.

In rare cases where longer text is needed (more than 6 lines), the header and body text are left aligned (right aligned for RTL) to facilitate readability.

On scroll, the Actions area remains persistent and Depth 3 is applied.

In Other Elements

Empty State patterns can occur inside of specific components where necessary, but it is important to consider whether the component needs to be shown at all.

Examples

Examples of the Empty State component include errors such as “Not Found,” “Something Went Wrong,” “Access Restricted,” “Connection Refused,” “Open in Browser” and required & optional software updates. For guidance for and examples of these Empty State patterns, see the Empty State Figma spec.

API Guidelines

The Empty State component is built with SwiftUI and provides a flexible API for displaying empty states and errors.

EmptyStatePage

The main view component that should be used in your SwiftUI views. This component handles analytics and localization.

EmptyStatePage(
    featureData: FeatureMetricsData,
    localizer: LocalizationAdapting,
    errorState: EmptyStateViewModelTemplate
)

EmptyStateViewModelTemplate

An enum that provides pre-built empty state configurations for common scenarios:

case pageNotAvailable(ButtonAction?)                        // 404 errors
case somethingWentWrong(ButtonAction?, ButtonAction?)       // 500 errors
case accessRestricted(ButtonAction?)                        // 403/401 errors
case connectionRefused(ButtonAction?, ButtonAction?)        // Network issues
case appUpdateRequired(ButtonAction?)                       // Required updates
case optionalUpdateAvailable(ButtonAction?, ButtonAction?)  // Optional updates
case osUpdateRequired(ButtonAction?)                        // OS requirements
case continueToBrowser(ButtonAction?)                       // Browser redirects
case custom(EmptyStateViewModel)                            // Custom states

Custom Empty States

For custom empty states, create an EmptyStateViewModel:

let viewModel = EmptyStateViewModel(
    imageName: String,  // from WDIcons
    localizedTitle: String,
    localizedMessage: String?,
    mainButtonConfig: EmptyStateButtonConfig
)

Button Configuration

Configure action buttons using EmptyStateButtonConfig:

EmptyStateButtonConfig(
    localizedTitle: String,
    action: () -> Void
)

Common Examples

404 Error

EmptyStatePage(
    featureData: featureData,
    localizer: localizer,
    emptyState: .pageNotAvailable {
        navigationController.popViewController(animated: true)
    }
)

Custom Empty State View Model

EmptyStateViewModel(
    imageName: GraphicNames.empty_state_search_colored,
    localizedTitle: "No Documents Yet",
    localizedMessage: "Create your first document to get started",
    mainButtonConfig: .init(
        localizedTitle: "Create Document",
        action: createDocument
    )
)

1. Illustration: A visual representation of the situation.
2. Title: A concise explanation of the situation.
3. Message (Optional): Supporting information and/or a suggestion to take a first action or fix the error.
4. Primary Action (Optional): The suggested action to take a first action or resolve an error.
5. ** Secondary Action (Optional):** Generally represents an exit or way back. This may be omitted for required software updates or in cases where there is no content as this is a first usage.

Usage Guidance

When to Use

• When navigating to a task for the first time and no content displays because it needs to be added or created first.
• When navigating to a page that fails to load, whether due to server or connectivity issues.
• When navigating to a page that a user doesn’t have security access to.
• When an app update is required or recommended in order to view app content.

When to Consider Something Else

• In the case of an error, if part of the page content can be loaded, use a Banner to indicate an error instead.
• To display input level error validation, use a Banner.
• If an element or link will never be available to users, consider hiding the element rather than routing users to an error Empty State.
• If error information is critical and requires user action or decision, consider using an Alert Dialog. Alert Dialogs are reserved for messages of the highest priority; they command user action by blocking any other interactions.
• If communicating updates about the progress of an application, consider using Snackbars; they do not require user action.

Behaviors

Page Loading

In error use cases, page loading animations persist until page load failure, then a full page error appears. The error remains until the user exits the app, navigates back to the previous page, or taps the primary action button.

In other Empty State use cases, the page loading animations persist until the page loads, then the full page Empty State displays.

Both failed page loading and Empty States use a 150ms fade-in of the full-page error, replacing the existing loading indicator.

Actions

Onboarding / First Time Use

Empty States are a pivotal point in the user journey. They are opportunities to build rapport, drive engagement, educate, or delight the user. Empty States should never actually feel empty.

Onboarding or first time Empty States generally display a primary action only. This primary action should try to offer a logical first step (“Create a Document” “Start a Referral”). See examples in the Empty State Figma spec.

Errors

Error Empty States generally display a primary and secondary option. The primary action should provide a remedy for the error (“Refresh,” “Continue to Browser”). The secondary action should offer a way out (“Go Back”). Where no remedy is available, use “Go Back” as the primary action.

If “Refresh” is an option, once “Refresh Page” is tapped, the page should attempt to reload or refresh. If the error persists then the Full Page Error should reappear. If the error is resolved the normal content should appear for that page.

Longer Empty State Messages

In general, Empty State messages should be concise. Follow the content recommendations in Error and Alert Messages and Empty States.

In rare cases where longer text is needed (more than 6 lines), the header and body text are left aligned (right aligned for RTL) to facilitate readability.

On scroll, the Actions area remains persistent and Depth 3 is applied.

In Other Elements

Empty State patterns can occur inside of specific components where necessary, but it is important to consider whether the component needs to be shown at all.

Examples

Examples of the Empty State component include errors such as “Not Found,” “Something Went Wrong,” “Access Restricted,” “Connection Refused,” “Open in Browser” and required & optional software updates. For guidance for and examples of these Empty State patterns, see the Empty State Figma spec.

API Guidelines

Coming soon!