Description

Paper-stepper is an element made with Polymer with respect to the material specifications.

Steppers display progress through a sequence by breaking it up into multiple logical and numbered steps. They may also be used for navigation.

Spec recommendation: Avoid using steppers to break up sections in a short form, or multiple times on one page and don’t embed steppers within steppers.

Start using now bower install -S Zecat/paper-stepper#v2.0-beta.5

Note, it is still a beta release, attributes and methods might change suddenly.

Configuration

Paper-stepper is a container for paper-step's. Give a label to your steps, once the user tap the primary button, the step is saved and the stepper progress. He can come back to update a saved step if it has editable attribute set.

• Editable steps allow users to return later to edit a step. These are ideal for workflows that involve editing steps within a session.
• Non-editable steps should be used when the users cannot edit a step later and when step editing poses a distraction risk to form completion.

Include any content you want in a step, simply ensure that the contents for each step are responsive and don’t embed steppers within steppers. If the content overflow, the step will be scrollable.

The stepper is non-linear by default, which allow users to enter a multi-step flow at any point whereas a linear stepper requires users to complete one step in order to move on to the next.

optional steps don't bloc the progression in linear stepper [Missing feature]. You can configure the text displayed which default to "optional" with optional-text attribute.

Validation

Paper-step implement IronValidatableBehavior. Override _getValidity() method on a step to create your own validation logique.

Layout

Paper-stepper is horizontal by default. Horizontal steppers are ideal when the contents of one step depend on an earlier step. Avoid using long step names in horizontal steppers.

The alternative label take effect in horizontal layout and allows slightly longer labels.

Use the vertical layout for narrow screen sizes, when your labels are too long or when you have too many steps. It is ideal for mobile.

If you specify --paper-stepper-vertical-responsive-width, the stepper manage the vertical attribute itself. When the width of the stepper (not the viewport width!) is inferior to the variable, the vertical layout is use.

For performance reason, the responsive check is debounced according to responsive-check-frequence which default to 200ms.

Resize your window to see the effect.

Buttons

• Set has-back-button if you want a back button, the back action send you to the previous sibling selectable step and is disabled if this step doesn't exist.
• Set has-skip-button if you want a skip button. The skip action loops around the steps to find the next selectable unsaved step. If this step doesn't exist, the button is disabled.

You can configure the text of the above buttons with back-text and skip-text attributes.

The text of the primary button correspond to continue-text attribute by default, update-text if the step is saved and finish-text if it is the last unsaved step. Texts are capitalized within the buttons.

Styling

In vertical layout, the height of the stepper depends on his steps and in an opened horizontal stepper, it defaults to 450px.

Use the following variables instead of setting 'height' and 'max-height', they allow to configure the stepper and its steps depending on the layout.

Stepper CSS variables

• --paper-stepper-horizontal-opened-height : the height of paper stepper in horizontal layout when it is opened, default to 450px.
• --paper-stepper-vertical-max-height: the max height of the vertical stepper, not defined by default.
• --paper-stepper-horizontal-opening-transition-duration: the horizontal stepper opening transition duration, default to 500ms.

Steps CSS variables

• --paper-vertical-step-transition-duration: the vertical step opening transition duration, default to 500ms.
• --paper-vertical-step-max-height: the max-height of the content of your step, default to 400px.

Selection

Paper-stepper implement IronSelectableBehavior. By default, selected reflet the selected index (the first step has index 0). Give a default value to selected for the step to be opened when the user land on the stepper.

Note: The behavior is slightly modified to only allow the selection of selectable steps.

You can use attr-for-selected for selected to reflect an attribute on your step.

Animations

You can define animations between steps in horizontal layout. Import your animations and set

• horizontal-higher-entry-animation
• horizontal-lower-entry-animation
• horizontal-higher-exit-animation
• horizontal-lower-exit-animation

to the name of the wanted animation, directly on paper-stepper or on a specific paper-step.

Events

• paper-stepper-completed is fired from the stepper when all the steps are saved.
• paper-step-saved is fired from a step when it become saved.
• paper-step-updated is fired from a step it is saved again.

Methods

Binding

You can bind these attributes to be notified of changes about the stepper and its steps.

Extra

In horizontal layout, labels are overflow ellipsis and will be revealed on hover. For long labels, prefer use alternative label or vertical layout.

By-product: This demo is made with iron-scroll-spy, fork!

Sandbox

Change on an attribute will be immediately reflected.