@financial-times/o-stepped-progress v4.0.9

o-stepped-progress

Track progress through a multi-step process, such as a form.

• Usage
• Markup
• JavaScript
• Sass
• Migration Guide
• Contact
• Licence

Usage

Check out how to include Origami components in your project to get started with o-stepped-progress.

Markup

The markup for a stepped progress element is as follows. Markup is commented for clarity, and to explain why additional elements are used which may otherwise seem redundant.

<!--
Base class and attribute hook for JavaScript
-->
<div class="o-stepped-progress" data-o-component="o-stepped-progress">

	<!--
	The steps live in an ordered list, which ensures that assistive
	technology can read this appropriately. Also if CSS does not load
	then a sensible fallback is in place
	-->
	<ol class="o-stepped-progress__steps">

		<!--
		Each step lives inside a list item. This item does not need any
		classes applied. The following modifiers are available to indicate
		the status of a step (each prefixed with o-stepped-progress):
		  - complete: a step that has been completed by the user
		  - current: the step the user is currently on
		  - error: a step that something went wrong with
		-->
		<li>

			<!--
			The step itself is either an anchor or span element. We encourage
			using an anchor for completed and current steps, as this offers a
			better experience for screen readers - all of the text inside is
			read as one block rather than each span separately.
			-->
			<a href="/step-1" class="o-stepped-progress__step o-stepped-progress__step--complete">
				<span class="o-stepped-progress__label">

					<!--
					The o-stepped-progress__status element is required to make
					the step label accessible for assistive technology, older
					browsers, and when CSS fails to load. This element is
					visually hidden otherwise
					-->
					Example Completed Step <span class="o-stepped-progress__status">(completed)</span>
				</span>
			</a>
		</li>

		<!--
		An example of the current step. Here using an anchor element
		and including accessible text in the label
		-->
		<li>
			<a href="/step-2" class="o-stepped-progress__step o-stepped-progress__step--current">
				<span class="o-stepped-progress__label">
					Example Current Step <span class="o-stepped-progress__status">(current step)</span>
				</span>
			</a>
		</li>

		<!--
		An example of a future step (with no modifier classes). Here
		we're using a span element as we don't want a user to jump
		ahead before completing the current step. Future steps do
		not require a status element
		-->
		<li>
			<span class="o-stepped-progress__step">
				<span class="o-stepped-progress__label">
					Example Future Step
				</span>
			</span>
		</li>

	</ol>
</div>

JavaScript

No code will run automatically unless you are using the Build Service. You must either construct an o-stepped-progress object or trigger an o.DOMContentLoaded event, which o-stepped-progress listens for.

Constructing an o-stepped-progress instance manually

Assuming that you have an HTML element on the page to represent your stepped progress:

import SteppedProgress from '@financial-times/o-stepped-progress';
const steppedProgressElement = document.getElementById('my-stepped-progress');
const mySteppedProgress = new SteppedProgress(steppedProgressElement);

If you want to initialise every stepped progress element on the page (based on the presence of the attribute: data-o-component="o-stepped-progress"):

import SteppedProgress from '@financial-times/o-stepped-progress';
SteppedProgress.init();

Constructing o-stepped-progress instances automatically

You can also rely on the o.DOMContentLoaded event to initialise all Origami components that have been included in your JavaScript. Either use o-autoinit or dispatch the event yourself once all of your page content has loaded:

document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));

Interacting with an o-stepped-progress instance

Once you have stepped progress instances, you can interact with them using the methods below:

• mySteppedProgress.getSteps(): Get an array of the steps in the stepped progress component
• mySteppedProgress.getCompletedSteps(): Get an array of the steps that are completed
• mySteppedProgress.getCurrentStep(): Get the step marked as current
• mySteppedProgress.isComplete(): Get whether the stepped progress has been completed
• mySteppedProgress.progress(): Mark the current step as complete, and move onto the next step

There is full API documentation available in the Origami Registry.

Sass

To output all styles call @include oSteppedProgress(); in your Sass:

@import '@financial-times/o-stepped-progress/main';
@include oSteppedProgress();

Mixin: oSteppedProgress

The oSteppedProgress mixin is used to output base styles as well as styles for all of the available themes. This output includes all of the .o-stepped-progress classes:

@include oSteppedProgress();

.o-stepped-progress {
	/* styles */
}
.o-stepped-progress--heavy {
	/* styles */
}
/* etc. */

If you wish to specify a subset of themes to output styles for, you can pass in an $opts parameter (see themes for available options):

@include oSteppedProgress($opts: (
	'themes': (
		'heavy'
	)
));

There is full Sass documentation available in the Origami Registry.

Themes

This table outlines all of the possible themes you can request in the oSteppedProgress mixin:

Migration guide

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.

Licence

This software is published by the Financial Times under the MIT licence.