Stepper #
Stepper allows users to separate content into several steps and navigate through it using buttons or timeline.
Examples #
Basic usage #
- Select a category
- Browse products
- Add to cart
Vertical #
- Select a category
- Browse products
- Add to cart
Custom icons #
Each step config could have icon name specified, check va-icon for more details.
- Select a category
- Browse products
- Add to cart
Customized with slots #
- Select a category
- Browse products
- Add to cart
You can iterate through slots using template literals in slot name.
Example: #[`step-button-${i}`]="{ setStep, isActive, isCompleted }"
Navigation only #
You can hide controls and use stepper navigation independently
Custom save action for each step #
This adds a property of beforeLeave that accepts a function. When you click next previous or click on a navigation item at the top, your function will be called. If beforeLeave returns false navigation is disabled. You can also set hasError using this function.
Validate on save
Linear #
Prevent navigation to the step if any of previous steps have error. It means that you can't go to the next step until you fix the error. You can set hasError in beforeLeave function.
Validation using VaForm #
You must use const formRef = ref(); useForm(formRef) instead of useForm('formRef'). Vue will not update form ref when slots updated while using script setup
Accessibility #
The component itself has a role="group" with aria attributes like an aria-orientation attribute that depends on the vertical property. The current step element has the attribute aria-current="step". Keyboard navigation for this component is based on the w3 tabs pattern.
API #
Props #
| Name | Description | Types | Default |
|---|---|---|---|
| ariaLabel | The aria-label of the component |
|
|
| color | Color of the component (theme string or |
|
|
| controlsHidden | Removes 'Back' and 'Next' buttons. |
|
|
| finishButtonHidden | Hides 'Finish' button |
|
|
| finishStep |
| - | |
| linear | Requires that each step must be manually marked as complete |
|
|
| modelValue | Value of current step starting from |
|
|
| navigationDisabled | Disables navigation via pressing on steps. |
|
|
| nextDisabled | Disables navigation to steps further than |
|
|
| nextDisabledOnError |
|
| |
| stateful | Add possibility to work with component without setting |
|
|
| steps | Array of step configs. |
|
|
| vertical | Changes stepper orientation to vertical. |
|
|
Events #
| Name | Description |
|---|---|
finish | Emits when 'Finish' button is getting pressed |
update:modelValue | The event is triggered when the component needs to change the model. Is also used by |
update:steps |
Slots #
| Name | Description |
|---|---|
controls | Inserts provided template after default controls. If you want to replace default controls set |
divider | Replaces step divider in the timeline with provided template. |
stepButton | Replaces the step in timeline with provided template. Step slots are enumerable and should be used with step number postfix (i.e. step-button-0, step-button-1, etc). Slot scope properties and methods available: |
stepContent | Replaces step content with provided template. Content slots are enumerable and should be used with step number postfix (i.e. step-content-0, step-content-1, etc). Slot scope properties and methods available: |
Methods #
| Name | Description |
|---|---|
nextStep | By default activates next step. If target step is disabled activates the step after it. |
prevStep | By default activates previous step. If target step is disabled activates the step before it. |
setStep | Activates step at specified index. |
Css Variables #
| Name | Default Value |
|---|---|
| --va-stepper-step-button-inactive-color | var(--va-secondary) |
| --va-stepper-step-button-hover-highlight-opacity | 0.1 |
| --va-stepper-step-button-disabled-opacity | 0.5 |
| --va-stepper-step-button-padding | 1rem |
| --va-stepper-step-button-number-size | 1.2rem |
| --va-stepper-step-button-icon-size | 2rem |
| --va-stepper-step-button-gap | 0.5rem |
| --va-stepper-step-button-icon-border-radius | 100% |
| --va-stepper-step-border-radius | var(--va-square-border-radius) |
| --va-stepper-divider-color | var(--va-secondary) |
| --va-stepper-divider-length | auto |
| --va-stepper-divider-min-length | 2rem |
| --va-stepper-divider-thickness | 1px |
| --va-stepper-divider-spacing | 0.5rem |
| --va-stepper-divider-vertical-margin-left | 2rem |
| --va-stepper-step-content-wrapper-padding | 0.5rem 1rem |
| --va-stepper-step-content-margin | 0.8rem 0 2rem |
| --va-stepper-controls-gap | 1rem |