Phase progress bar

Phase progress bar in Storybook

Usage

Overview

The phase progress bar displays the user's progress in completing a task, divided into distinct phases.

When to use

• To display steps and sub-steps for a specific task.
• When you need to use custom icons.

When not to use

If you are unsure of the number of steps required to complete the task. Instead, use a simple progress bar.

Formatting

Anatomy

The phase layout consists of the following elements:

1. Phase icon: Indicates if a phase is completed, in progress, or pending. You can use different icons with the phase progress bar to customize the experience.
2. Bar: Connects the phases visually.
3. Phase label: Provides context for each phase (for example, "Payment").

Best practices

• Ensure the steps are displayed in a logical order, from start to end (left to right).
• Users must be able to return to previous steps for review and to update details.
• Ensure the steps are logically grouped, simple, and clear to support understanding.
• Make sure all steps are visible.
• Keep the steps to a minimum of 3 and a maximum of 7.

Content

General writing guidelines

• Use sentence case for all aspects of designing Guidewire product interfaces. Don't use title case.
• Use present tense verbs and active voice in most situations.
• Use common contractions to lend your copy a more natural and informal tone.
• Use plain language. Avoid unnecessary jargon and complex language.
• Keep words and sentences short.

Phase label

• Keep labels short and clearly identify the step.
• Use sentence case for labels. Capitalize the first word of a phrase and any proper nouns. For additional guidance on how to implement sentence case, see Capitalization.
• When using tooltips in conjunction with a steps layout, tooltip content must only contain one or two words.

Interactions

Keyboard

Each active step can be focused on using the keyboard.

Screen reader

The phase progress bar represents an entire process. It contains a series of smaller independent progress bars that represent phases in that process. The component implements the HTML5 landmark <nav> tag and each individual phrase is identified by its name (through an aria-label value) and the WAI-ARIA role='link'.

Accessibility

The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.1 AA requirements. Non-textual content that needs to convey meaning (such as icons and keyboard focus visibility) has a contrast ratio of at least 3:1 with its adjacent colors. All content is visible and functional up to and including 400% without requiring scrolling in two dimensions.

This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance.

Code

<PhaseProgressBar
  phases={[
    {
      icon: BusinessCenterIcon,
      id: 'your-business',
      steps: [
        {
          title: 'Completed phase first step',
          visited: true,
        },
        {
          title: 'Completed phase second step',
          visited: true,
        },
      ],
      title: 'Completed Phase',
    },
    {
      icon: InsertDriveIcon,
      id: 'final-details',
      isError: false,
      steps: [
        {
          active: true,
          title: 'Active step',
          visited: true,
        },
        {
          title: 'Next step',
        },
      ],
      title: 'Current phase',
    },
    {
      icon: CreditCardIcon,
      id: 'payment',
      steps: [
        {
          title: 'Next phase step 1',
        },
        {
          title: 'Next phase step 2',
        },
        {
          title: 'Next phase step 3',
        },
      ],
      title: 'Next phase',
    },
  ]}
/>

Import statement

import { PhaseProgressBar } from '@jutro/components';

Component contract

Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.

Properties

Phase progress bar properties

phasesrequired

Type

PhaseProps[]

Description

List of phase objects in the progress indicator. These are the same props listed in the Phase properties table.

className

Type

string

Description

CSS class name for this component.

Phase properties

stepsrequired

Type

{ title: intlMessageShape, visited?: bool, active?: bool, disabled?: bool, onClick?: () => void) }[]

titlerequired

Type

intlMessageShape

Description

Text part for labeling the phase.

active

Type

string

Description

If set to true, this is the active step.

disabled

Type

string

Description

If set to true, this step is disabled.

onClick

Type

function (React.MouseEvent<HTMLElement>)

Description

On click event handler.

visited

Type

boolean

Description

If set to true, the user has already visited this step.

Description

Steps data.

titlerequired

Type

IntlMessageShape

Description

Text part for labeling the phase.

className

Type

string

Description

CSS class name for this component.

icon

Type

string | Icon

Description

An Icon component to render on the component. The value must be an Icon component or the icon's name. For example, CheckIcon or 'gw-check'.

id

Type

string

Description

Unique identifier for the component.

isError

Type

boolean

Description

Flag determining if phase will be shown as an error.

onClick

Type

function (React.MouseEvent<HTMLElement>)

Description

On click event handler.

showLabel

Type

boolean

Description

if set to true, the label will be displayed.

Hooks

ProgressLabelContext - Context about the phase progress labels.

Translation keys

ProgressIndicator messages can be used to display details on the users' current progress:

Key	Used for
jutro-components.widgets.progressIndicator.status.completed	Step is completed
jutro-components.widgets.progressIndicator.status.inProgress	Step is in progress
jutro-components.widgets.progressIndicator.progressStep.status.visited	Step has been visited
jutro-components.widgets.progressIndicator.ariaLabel	aria-label formed from combination of progressTitle and progressLabel

Escape Hatches

For more information, see our documentation about escape hatches.

Custom behaviors

Phone breakpoint

Automatically support phone breakpoints. Will not render phase labels if phone breakpoint detected.

Examples

Check out the Usage section for details about how to design a Phase progress bar properly, and the different configuration options we provide.

Basic phase progress bar example

Displays progress as a series of phases which in turn have a series of sub steps to complete.

<PhaseProgressBar
  phases={[
    {
      icon: BusinessCenterIcon,
      id: 'your-business',
      steps: [
        {
          title: 'Completed phase first step',
          visited: true,
        },
        {
          title: 'Completed phase second step',
          visited: true,
        },
      ],
      title: 'Completed Phase',
    },
    {
      icon: InsertDriveIcon,
      id: 'final-details',
      isError: false,
      steps: [
        {
          active: true,
          title: 'Active step',
          visited: true,
        },
        {
          title: 'Next step',
        },
      ],
      title: 'Current phase',
    },
    {
      icon: CreditCardIcon,
      id: 'payment',
      steps: [
        {
          title: 'Next phase step 1',
        },
        {
          title: 'Next phase step 2',
        },
        {
          title: 'Next phase step 3',
        },
      ],
      title: 'Next phase',
    },
  ]}
/>

Interactive Example

This example shows how the phase progress bar changes as a user progresses through the steps in each of its phases.

const [currentStage, setCurrentStage] = useState(0);
const [currentStep, setCurrentStep] = useState(0);
const initialPhases = [
  {
    title: 'First Phase',
    icon: BusinessCenterIcon,
    id: 'your-business',
    steps: [
      {
        title: 'First step',
        visited: true,
        active: true,
      },
      {
        title: 'Second step',
        visited: false,
      },
      {
        title: 'Third step',
        visited: false,
      },
    ],
  },
  {
    title: 'Second phase',
    icon: InsertDriveIcon,
    id: 'final-details',
    isError: false,
    steps: [
      {
        title: 'First step',
        visited: false,
      },
    ],
  },
];
const [phases, setPhases] = useState(initialPhases);
const [disableButton, setDisabledButton] = useState(false);
const [disableBackButton, setDisabledBackButton] = useState(true);
const [labelState, setLabelState] = useState('info');

const moveToNext = () => {
  let nextPhases = phases;
  let stage = currentStage;
  let step = currentStep;

  nextPhases[stage].steps[step].visited = true;
  nextPhases[stage].steps[step].active = false;

  if (stage == 0) {
    step < 2
      ? setCurrentStep(++step)
      : ((stage = 1), (step = 0), setCurrentStage(stage), setCurrentStep(step));
    nextPhases[stage].steps[step].active = true;
    setDisabledBackButton(false);
  } else {
    setDisabledButton(true);
    setLabelState('success');
  }

  setPhases(nextPhases);
};

const moveBack = () => {
  let nextPhases = phases;
  let stage = currentStage;
  let step = currentStep;

  nextPhases[stage].steps[step].visited = false;
  nextPhases[stage].steps[step].active = false;

  if (stage == 1) {
    stage = 0;
    step = 2;
    setCurrentStage(stage);
    setCurrentStep(step);
    nextPhases[stage].steps[step].active = true;
    nextPhases[stage].steps[step].visited = false;
    setLabelState('info');
    setDisabledButton(false);
  } else {
    step > 0
      ? setCurrentStep(--step)
      : ((stage = 1), (step = 0), setCurrentStage(stage), setCurrentStep(step));
    nextPhases[stage].steps[step].active = true;
    if (step == 0) {
      setDisabledBackButton(true);
    }
  }

  setPhases(nextPhases);
};

<JutroWrapper>
  <PhaseProgressBar phases={phases} />
  <br />
  <InfoLabel type={labelState}>Phase: {phases[currentStage].title}</InfoLabel>
  <InfoLabel type={labelState}>
    Step: {phases[currentStage].steps[currentStep].title}
  </InfoLabel>
  <br />
  <br />
  <Button
    label="previous"
    onClick={moveBack}
    disabled={disableBackButton}></Button>
  <Button
    label="next"
    onClick={moveToNext}
    disabled={disableButton}></Button>
</JutroWrapper>;

Error Example

You can highlight when there is an error within a phase.

<PhaseProgressBar
  phases={[
    {
      icon: BusinessCenterIcon,
      id: 'your-business',
      steps: [
        {
          title: 'Completed phase first step',
          visited: true,
        },
        {
          title: 'Completed phase second step',
          visited: true,
        },
      ],
      title: 'Completed Phase',
    },
    {
      icon: InsertDriveIcon,
      id: 'final-details',
      isError: true,
      steps: [
        {
          active: true,
          title: 'Active step',
          visited: true,
        },
        {
          title: 'Next step',
        },
      ],
      title: 'Current phase',
    },
  ]}
/>

OnClick Example

You can add a function that runs when the phase title is clicked.

function MakeToast (text: string) {
        ToastProvider.toast({
            message: text,
            autoClose: 3000,
          })
    }

<ToastProvider />
<PhaseProgressBar
    phases={[
        {
        icon: BusinessCenterIcon,
        id: 'your-business',
        steps: [
            {
            title: 'Completed phase first step',
            visited: true
            },
            {
            title: 'Completed phase second step',
            visited: true
            }
        ],
        title: 'Completed Phase',
        onClick: () => {MakeToast("Completed clicked")}
        },
        {
        icon: InsertDriveIcon,
        id: 'final-details',
        steps: [
            {
            active: true,
            title: 'Active step',
            visited: true
            },
            {
            title: 'Next step'
            }
        ],
        title: 'Current phase',
        onClick: () => {MakeToast("Current clicked")}
        }
    ]}
    />

Changelog

10.9.0

icon property type extended

The type of the icon property has been extended to string | React.ComponentType.

Deprecations

Passing a string as a value to the icon property has been deprecated.