Skip to main content
Version: v8.1.0-alpha.3

ontario-step-indicator

Use a step indicator to show a user’s progress as they move through a multi-step form.

Usage guidance​

Please refer to the Ontario Design System for current documentation guidance.

Configuration​

Once the component package has been installed (see Ontario Design System Component Library for installation instructions), the step indicator component can be added directly into the project's code, and can be customized by updating the properties outlined here. Please see the examples below for how to configure the component.

Examples​

Percentage​

<ontario-step-indicator
	show-back-button="true"
	back-button-url="https://designsystem.ontario.ca/"
	percentage-complete="70"
></ontario-step-indicator>

Steps​

<ontario-step-indicator
	show-back-button="true"
	back-button-url="https://designsystem.ontario.ca/"
	current-step="4"
	number-of-steps="5"
></ontario-step-indicator>

No back button​

<ontario-step-indicator show-back-button="false" current-step="4" number-of-steps="5"></ontario-step-indicator>

Enabling the back button​

By default the step indicator doesn't display the back button. This can be enabled by setting show-back-button to true. See the code examples for how this is used.

When the back button is enabled:

  • back-button-url / backButtonUrl renders the back control as a link
  • customOnClick renders the back control as a button
  • if both are provided, the link takes precedence and a warning is emitted
  • if neither is provided, the button still renders and a warning is emitted

Progress reporting​

Progress reported by the step indicator can be displayed in either a percentage or as the number of completed steps.

When percentage-complete / percentageComplete is provided, the component uses percentage mode. This includes 0.

If percentage and step props are passed together, percentage mode takes precedence and a warning is emitted.

Using a percentage​

To use a percentage as the reported progress, set the percentage-complete attribute to the percentage the user has completed the form.

<ontario-step-indicator
	show-back-button="true"
	back-button-url="https://designsystem.ontario.ca/"
	percentage-complete="70"
></ontario-step-indicator>

Using steps​

To output the step the user is currently on and the total number of steps, set the current-step and the number-of-steps to the appropriate values.

If only one of the step props is provided, the component renders a ? placeholder for the missing value and emits a warning.

<ontario-step-indicator
	show-back-button="true"
	back-button-url="https://designsystem.ontario.ca/"
	current-step="4"
	number-of-steps="5"
></ontario-step-indicator>

Custom back button function​

The simplest use of the back button is to provide, via the back-button-url attribute, a URL to navigate the user to when the back button is clicked. This isn't always sufficient to cover all use cases of the component so the component can also make use of a custom back button function, registered via the customOnClick property using JavaScript, to perform any custom actions within your application/site.

<ontario-step-indicator show-back-button="true" percentage-complete="70"></ontario-step-indicator>

<script>
	function handleBackButton(event) {
		event.preventDefault();
		// Additional logic here
	}

	const ontarioStepIndicator = document.querySelector('ontario-step-indicator');
	ontarioStepIndicator.customOnClick = handleBackButton;
</script>

Technical Note: SSR (Server-Side Rendering) Considerations​

The Ontario Step Indicator component supports server-side rendering, with a few considerations:

  • Language prop: Pass language explicitly during SSR.
  • Hydrated-only language events: Avoid relying on setAppLanguage or headerLanguageToggled for server-rendered output, because these events only fire after hydration.
  • Framework guidance: For deterministic SSR output, set language directly in markup (for example, <ontario-step-indicator language="fr"></ontario-step-indicator>).

Overview​

Ontario Step Indicator communicates progress through multi-step flows.

For component guidance, see:

Properties​

PropertyAttributeDescriptionTypeDefault
backButtonUrlback-button-urlURL for the back element to set a path for where the link will lead. If a URL is passed in, the back element will display as an anchor tag. The back element will require either the backButtonURL prop or the customOnClick prop to be passed in order for the back element to display.string | undefinedundefined
currentStepcurrent-stepA number value to indicate which step the user is currently on.number | undefinedundefined
customOnClickcustom-on-clickUsed to add a custom function to the back button onClick event. If this function is passed in, the back element will display as a button. The back element will require either the backButtonURL prop or the customOnClick prop to be passed in order for the back element to display.((event: Event) => void) | undefinedundefined
languagelanguageThe language of the component. This is used for translations, and is by default set through event listeners checking for a language property from the header. If none are passed, it will default to English."en" | "fr" | undefinedundefined
numberOfStepsnumber-of-stepsA number value to indicate to the user the total number of steps the form has.number | undefinedundefined
percentageCompletepercentage-completeA number value to indicate to the user the percentage of the form that has been completed.number | undefinedundefined
showBackButtonshow-back-buttonA boolean value to determine whether or not the back button is displayed for the step indicator. This is optional. If no prop is passed, it will default to false.boolean | undefinedfalse

Dependencies​

Depends on​

Graph​

Built with StencilJS