Building blocks

A
B
C
D
E
J
K
F
G
H
I
A
B
C
D
J
K
F
G
H

A.
Breadcrumbs

Navigation links at the top of the pages in a flow. Breadcrumbs have three entries:

First: Use the service name for the root page in the breadcrumbs, and make it a link. For the last entry in the breadcrumbs, use Edit.

Second: Use the title of the page to indicate what the user is doing in the current step. Begin the title with an active verb and format it as heading 1. The title begins with an active verb. Use the following: Create [resource name]

Third: The last breadcrumb is the title of the multipage create flow. This is the only place that displays the title of the overall flow.

B.
Wizard

Use the wizard component for this pattern. Use it to configure the navigation pane, form header, main content area, action buttons, and optional review page.

C.
Info link

Use the 'Info' link next to the label or section title to trigger the help panel.

D.
Container

A container contains multiple form fields and uses an h2 heading. You can have more than one container on a page.
Keep the order of sections consistent between the steps and the review page.

E.
Form field

Include a field label describing the corresponding control (Examples: text inputs, dropdown lists, check boxes, and radio buttons). If you need additional explanation, you can add a form description. Apply standard validation for each field input.

F.
Step titles in review

Break down the review page by each step of the create flow. Label each step with the same step title as presented in both the navigation pane and page titles, but without the prefixed verb.

G.
Edit buttons

Inline edit buttons on the review page navigate the user back to each correspond step page.

H.
Key-value pairs

When there are three or more key-value pairs, organize the contents of a container on the review page into two columns. You can use tables to display inputs for long datasets. For example, a list of tags.

I.
Additional expandable section

If necessary, include a section for advanced configuration. Follow the guidelines on single page create.
Any additional settings present in a form should persist on the review page and be closed by default.

J.
Side navigation

Navigation is closed by default on forms. You can learn more about structuring side navigation content in service navigation.

K.
Help panel

Place supplemental, helpful information in the Help panel. For more information about structuring help content and how users can open help panels, see help system.

-.
Alert (not shown)

Instructions that tell users how to recover from server side page errors. For more information, see validation.

Key UX concepts

Review page

The last page of the flow summarizes the choices made in previous steps for quick review in the same order that was presented in the flow. Users can review their information on the page and quickly go back to any step for edits. Avoid including interactions on the page such as inline editing or editing modals, to keep the focus of the page on review. The page is optional but recommended.

Validation

There are two types of validation, which are frequently used together:

  • Form field validation: Most often used for client-side validation, which processes information and provides feedback, before the form is sent.

    • This feedback is presented as error text on individual form fields.

    • It’s best used for validating specific values such as: missing required fields, incorrect formatting of values, and unacknowledged confirmation fields.

    • This type of validation can be invoked on the completion of each field or upon form submission or transition to the next step in a wizard.

  • Page level form validation: Most often used for server-side validation, which processes information after the form is submitted, and returns either a success or failure.

    • This feedback is presented in one of two ways: either as a page level alert above the form's action buttons (in the case of a recoverable failure), or a flash on the page following submission (in the case of success or immutable failure).

    • It's best used for validating requests to the server that result in recoverable errors such as: insufficient capacity, exceeded request limits, and permission errors that can be updated. Failure messages should be communicated in the context of the form when possible, to prevent the user from having to re-enter any information.

    • This type of validation is launched upon form submission or transition to the next step in a wizard.

Exiting the wizard

Users can exit the wizard at any time. If a user has unsaved changes in the form and attempts to exit before completing the flow, you must prompt users with a modal asking them to confirm that they want to exit the flow. If there is no user input, you may end the multipage creation flow without a prompt.

General guidelines

Do

  • Apply the recommended max content area width and default panel states by setting contentType='wizard' in the app layout component.
  • Restrict the flow to minimal mandatory inputs and pages.
  • You can use up to seven pages if necessary, but we recommend using three to five pages in the flow.
  • Each step is a single page.
  • If there are unsaved changes in the flow, launch a modal upon exiting.
  • The user can go back and edit previous choices.
  • Apply standard form validation.

Writing guidelines

Breadcrumbs

The last breadcrumb item should not change while navigating through the form.

Step or form titles

Follow the writing guidelines for wizard and form headers.

Page descriptions

Follow the writing guidelines for form descriptions.

Container headings

Begin container headings with a noun. Follow the writing guidelines for headers.

Container descriptions

Follow the writing guidelines for headers.

Form

Follow the general writing guidelines for forms.

Placeholders in fields

Follow the writing guidelines for placeholders in inputs.

Defaults in fields

Follow the writing guidelines for select.

Constraint text

Follow the writing guidelines for form fields.

Buttons

Follow the writing guidelines for wizard action buttons.

Accessibility guidelines

  • Make navigation links, form inputs, and buttons keyboard accessible, in a logical order.

  • Follow the accessibility guidelines for forms.

Related patterns and components

With the create new resource pattern, users can create new resources.
Use single page create if you want your users to create a resource on a single page. This component is optimized for simple to medium-complex forms.
A multi-page form that guides a user through a complex flow or a series of interrelated tasks. A wizard consists of a navigation pane, header, main content area, and action buttons.