Origami Frontend Components & Services

Readme: o-stepped-progress

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

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:

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:

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

Migration guide

State Major Version Last Minor Release Migration guide
✨ active 4 N/A migrate to v4
⚠ maintained 3 3.2 migrate to v3
╳ deprecated 2 2.0 migrate to v2
╳ deprecated 1 1.0 N/A

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.

Status
active
Switch component view

GitHub: o-stepped-progress@4.0.2

Install o-stepped-progress

If using the Build Service, add o-stepped-progress@^4.0.2 to your script and link tags.

If using the npm package manager for a Manual Build, run npm install --save-peer "@financial-times/o-stepped-progress@^4.0.2".

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: #origami-support
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: #origami-support
Email: origami.support@ft.com