Track progress through a multi-step process, such as a form
npm install @financial-times/o-stepped-progressTrack progress through a multi-step process, such as a form.
- Usage
- Markup
- JavaScript
- Sass
- Migration Guide
- Contact
- Licence
Check out how to include Origami components in your project to get started with o-stepped-progress.
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.
`` html`
href="/step-1"
class="o-stepped-progress__step o-stepped-progress__step--complete"
>
Example Completed Step
(completed)
href="/step-2"
class="o-stepped-progress__step o-stepped-progress__step--current"
>
Example Current Step
(current step)
Example Future Step
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.
Assuming that you have an HTML element on the page to represent your stepped progress:
`js`
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"):
`js`
import SteppedProgress from '@financial-times/o-stepped-progress';
SteppedProgress.init();
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:
`js`
document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
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 componentmySteppedProgress.getCompletedSteps()
- : Get an array of the steps that are completedmySteppedProgress.getCurrentStep()
- : Get the step marked as currentmySteppedProgress.isComplete()
- : Get whether the stepped progress has been completedmySteppedProgress.progress()
- : Mark the current step as complete, and move onto the next step
There is full API documentation available in the Origami Registry.
To output all styles call @include oSteppedProgress(); in your Sass:
`scss`
@import '@financial-times/o-stepped-progress/main';
@include 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:
`scss`
@include oSteppedProgress();
`css`
.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):
`scss`
@include oSteppedProgress(
$opts: (
'themes': (
'heavy',
),
)
);
There is full Sass documentation available in the Origami Registry.
This table outlines all of the possible themes you can request in the oSteppedProgress` mixin:
| Theme | Description | Brand support |
| ----- | ----------------------------------------- | ------------- |
| heavy | Label with heavier lines and larger type. | internal |
| State | Major Version | Last Minor Release | Migration guide |
| :----------: | :-----------: | :----------------: | :---------------------------------------------------: |
| ⚠ maintained | 5 | N/A | migrate to v5 |
| ╳ deprecated | 4 | 4.0 | migrate to v4 |
| ╳ deprecated | 3 | 3.2 | migrate to v3 |
| ╳ deprecated | 2 | 2.0 | migrate to v2 |
| ╳ deprecated | 1 | 1.0 | N/A |
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.
This software is published by the Financial Times under the MIT licence.