Origami Frontend Components & Services

Readme: o-stepped-progress

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

Usage

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 '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 '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:

There is full API documentation available in the Origami Registry.

Sass

Silent mode

As with all Origami components, o-stepped-progress has a silent mode. To use its compiled CSS (rather than incorporating its mixins into your own Sass) set $o-stepped-progress-is-silent: false; in your Sass before you import the o-stepped-progress Sass:

$o-stepped-progress-is-silent: false;
@import 'o-stepped-progress/main';

Mixin: oSteppedProgress

If using o-stepped-progress in silent mode, you'll need to use the mixins outlined here to output styles.

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:

Theme Description Brand support
heavy Label with heavier lines and larger type. internal

Contact

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

Licence

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

Switch component view

GitHub Repository

Install o-stepped-progress

If using the Build Service, add o-stepped-progress@^1.0.0 to your script and link tags. Ensure the correct brand is set with a query parameter &brand=internal.

If running a Manual Build, run bower install --save "o-stepped-progress@^1.0.0".

Help & Support

o-stepped-progress is maintained directly by the Origami team. If you have any questions about o-stepped-progress or Origami in general, we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #ft-origami
Email: origami.support@ft.com