Light Dark System

Stepper

<zn-stepper> | ZnStepper
Since 1.0 experimental

Steppers provide visual feedback about progress through a multi-step process or workflow. 

<zn-stepper caption="Setup Progress" label="Installation Wizard" steps="5" value="3" show-progress></zn-stepper>

Examples

Basic Stepper

A basic stepper displays progress through a sequence of steps. Use the steps attribute to define the total number of steps and value to indicate the current step position. 

<zn-stepper steps="4" value="2"></zn-stepper>

With Caption

Use the caption attribute to add a descriptive label above the stepper. This helps users understand what process or workflow the stepper represents. 



<zn-stepper caption="Account Setup" steps="5" value="2"></zn-stepper>
<br />
<zn-stepper caption="Order Processing" steps="6" value="4"></zn-stepper>
<br />
<zn-stepper caption="Project Onboarding" steps="3" value="1"></zn-stepper>

With Label

Use the label attribute to display information above the caption. This is useful for showing the wizard or workflow name. 


<zn-stepper label="New User Registration" caption="Personal Information" steps="5" value="1"></zn-stepper>
<br />
<zn-stepper label="Checkout Process" caption="Shipping Details" steps="4" value="2"></zn-stepper>

Showing Progress Count

Use the show-progress attribute to display the current step number alongside the total number of steps (e.g., “2 / 5 steps”). 



<zn-stepper caption="Installation" steps="5" value="2" show-progress></zn-stepper>
<br />
<zn-stepper caption="Data Import" steps="10" value="7" show-progress></zn-stepper>
<br />
<zn-stepper caption="Configuration" steps="3" value="3" show-progress></zn-stepper>

Complete Progress States

Examples showing different stages of a workflow, from start to completion.




<zn-stepper
  label="Project Setup Wizard"
  caption="Getting Started"
  steps="5"
  value="0"
  show-progress>
</zn-stepper>
<br />
<zn-stepper
  label="Project Setup Wizard"
  caption="Configure Settings"
  steps="5"
  value="2"
  show-progress>
</zn-stepper>
<br />
<zn-stepper
  label="Project Setup Wizard"
  caption="Review & Deploy"
  steps="5"
  value="4"
  show-progress>
</zn-stepper>
<br />
<zn-stepper
  label="Project Setup Wizard"
  caption="Complete!"
  steps="5"
  value="5"
  show-progress>
</zn-stepper>

All Properties Combined

A comprehensive example showing all available properties working together.

<zn-stepper
  label="E-commerce Checkout"
  caption="Payment Information"
  steps="4"
  value="3"
  show-progress>
</zn-stepper>

Dynamic Progress Updates

Steppers can be updated dynamically using JavaScript to reflect real-time progress through a workflow.


Next Step Previous Step Reset 
<zn-stepper
  id="dynamic-stepper"
  label="Form Wizard"
  caption="Step 1: Personal Details"
  steps="4"
  value="1"
  show-progress>
</zn-stepper>
<br />
<zn-button id="next-step">Next Step</zn-button>
<zn-button id="prev-step" color="secondary">Previous Step</zn-button>
<zn-button id="reset-stepper" color="transparent">Reset</zn-button>

<script type="module">
  const stepper = document.getElementById('dynamic-stepper');
  const nextBtn = document.getElementById('next-step');
  const prevBtn = document.getElementById('prev-step');
  const resetBtn = document.getElementById('reset-stepper');

  const stepNames = [
    'Personal Details',
    'Contact Information',
    'Preferences',
    'Review & Submit'
  ];

  function updateStepCaption() {
    const stepIndex = stepper.value - 1;
    if (stepIndex >= 0 && stepIndex < stepNames.length) {
      stepper.caption = `Step ${stepper.value}: ${stepNames[stepIndex]}`;
    } else if (stepper.value === 0) {
      stepper.caption = 'Getting Started';
    }
  }

  nextBtn.addEventListener('click', () => {
    if (stepper.value < stepper.steps) {
      stepper.value = stepper.value + 1;
      updateStepCaption();
      if (stepper.value === stepper.steps) {
        stepper.caption = 'Complete!';
      }
    }
  });

  prevBtn.addEventListener('click', () => {
    if (stepper.value > 0) {
      stepper.value = stepper.value - 1;
      updateStepCaption();
    }
  });

  resetBtn.addEventListener('click', () => {
    stepper.value = 1;
    updateStepCaption();
  });
</script>

Multi-Step Form Wizard

A practical example showing a stepper integrated with a form wizard interface.

Basic Information

Please enter your basic details to get started.

Next 
<zn-stepper
  id="wizard-stepper"
  label="Account Creation Wizard"
  caption="Step 1: Basic Information"
  steps="3"
  value="1"
  show-progress>
</zn-stepper>

<div id="wizard-content" style="margin-top: 20px; padding: 20px; border: 1px solid rgb(var(--zn-border-color)); border-radius: 4px;">
  <div class="wizard-step" data-step="1">
    <h3>Basic Information</h3>
    <p>Please enter your basic details to get started.</p>
  </div>
  <div class="wizard-step" data-step="2" style="display: none;">
    <h3>Account Settings</h3>
    <p>Configure your account preferences.</p>
  </div>
  <div class="wizard-step" data-step="3" style="display: none;">
    <h3>Confirmation</h3>
    <p>Review your information and complete the setup.</p>
  </div>
</div>

<div style="margin-top: 20px;">
  <zn-button id="wizard-next" color="default">Next</zn-button>
  <zn-button id="wizard-prev" color="secondary" style="display: none;">Previous</zn-button>
  <zn-button id="wizard-finish" color="success" style="display: none;">Finish</zn-button>
</div>

<script type="module">
  const wizardStepper = document.getElementById('wizard-stepper');
  const nextBtn = document.getElementById('wizard-next');
  const prevBtn = document.getElementById('wizard-prev');
  const finishBtn = document.getElementById('wizard-finish');
  const steps = document.querySelectorAll('.wizard-step');

  const stepTitles = [
    'Basic Information',
    'Account Settings',
    'Confirmation'
  ];

  function updateWizard() {
    const currentStep = wizardStepper.value;

    // Update stepper caption
    wizardStepper.caption = `Step ${currentStep}: ${stepTitles[currentStep - 1]}`;

    // Show/hide content
    steps.forEach((step, index) => {
      step.style.display = (index + 1 === currentStep) ? 'block' : 'none';
    });

    // Show/hide buttons
    prevBtn.style.display = currentStep > 1 ? 'inline-block' : 'none';
    nextBtn.style.display = currentStep < wizardStepper.steps ? 'inline-block' : 'none';
    finishBtn.style.display = currentStep === wizardStepper.steps ? 'inline-block' : 'none';
  }

  nextBtn.addEventListener('click', () => {
    if (wizardStepper.value < wizardStepper.steps) {
      wizardStepper.value++;
      updateWizard();
    }
  });

  prevBtn.addEventListener('click', () => {
    if (wizardStepper.value > 1) {
      wizardStepper.value--;
      updateWizard();
    }
  });

  finishBtn.addEventListener('click', () => {
    alert('Wizard completed!');
  });

  updateWizard();
</script>

Installation Progress Simulation

A realistic example simulating an installation or setup process with automatic progress updates.


Start Installation Cancel 
<zn-stepper
  id="install-stepper"
  label="Software Installation"
  caption="Click Start to begin"
  steps="5"
  value="0"
  show-progress>
</zn-stepper>
<br />
<zn-button id="start-install" icon="download">Start Installation</zn-button>
<zn-button id="cancel-install" color="secondary" disabled>Cancel</zn-button>

<script type="module">
  const installStepper = document.getElementById('install-stepper');
  const startBtn = document.getElementById('start-install');
  const cancelBtn = document.getElementById('cancel-install');
  let installInterval;

  const installSteps = [
    'Downloading files...',
    'Extracting packages...',
    'Installing dependencies...',
    'Configuring settings...',
    'Finalizing installation...',
    'Installation complete!'
  ];

  startBtn.addEventListener('click', () => {
    installStepper.value = 0;
    startBtn.disabled = true;
    startBtn.loading = true;
    cancelBtn.disabled = false;

    let currentStep = 0;

    installInterval = setInterval(() => {
      if (currentStep < installStepper.steps) {
        currentStep++;
        installStepper.value = currentStep;
        installStepper.caption = installSteps[currentStep];
      } else {
        clearInterval(installInterval);
        installStepper.caption = installSteps[installSteps.length - 1];
        startBtn.disabled = false;
        startBtn.loading = false;
        cancelBtn.disabled = true;
      }
    }, 1500);
  });

  cancelBtn.addEventListener('click', () => {
    clearInterval(installInterval);
    installStepper.caption = 'Installation cancelled';
    startBtn.disabled = false;
    startBtn.loading = false;
    cancelBtn.disabled = true;
  });
</script>

Multiple Steppers

Display multiple steppers to track different concurrent processes or workflows.




<zn-stepper
  label="Frontend Build"
  caption="Build Complete"
  steps="4"
  value="4"
  show-progress>
</zn-stepper>
<br />
<zn-stepper
  label="Backend Build"
  caption="Running Tests"
  steps="4"
  value="3"
  show-progress>
</zn-stepper>
<br />
<zn-stepper
  label="Database Migration"
  caption="Migrating Schema"
  steps="6"
  value="2"
  show-progress>
</zn-stepper>
<br />
<zn-stepper
  label="Asset Optimization"
  caption="Waiting to Start"
  steps="3"
  value="0"
  show-progress>
</zn-stepper>

Minimal Stepper

A clean, minimal stepper without any text labels, useful for compact layouts or when context is provided elsewhere. 



<zn-stepper steps="5" value="1"></zn-stepper>
<br />
<zn-stepper steps="5" value="3"></zn-stepper>
<br />
<zn-stepper steps="5" value="5"></zn-stepper>

Progress Overflow

The stepper handles cases where the value exceeds the total steps by capping the visual progress at 100%. 

<zn-stepper
  caption="Over Limit Example"
  steps="5"
  value="7"
  show-progress>
</zn-stepper>

Different Step Counts

Steppers work with any number of steps, from simple two-step processes to complex multi-step workflows.




<zn-stepper caption="Two Steps" steps="2" value="1" show-progress></zn-stepper>
<br />
<zn-stepper caption="Five Steps" steps="5" value="3" show-progress></zn-stepper>
<br />
<zn-stepper caption="Ten Steps" steps="10" value="6" show-progress></zn-stepper>
<br />
<zn-stepper caption="Twenty Steps" steps="20" value="15" show-progress></zn-stepper>

Customization

Styling with CSS

Customize the appearance of the stepper using CSS custom properties and standard CSS.

<zn-stepper
  class="custom-stepper"
  label="Custom Styled Stepper"
  caption="With Custom Colors"
  steps="5"
  value="3"
  show-progress>
</zn-stepper>

<style>
  .custom-stepper .step-progress {
    background-color: rgb(var(--zn-success));
  }

  .custom-stepper .step {
    background-color: rgba(var(--zn-success), 0.3);
  }

  .custom-stepper .header {
    color: rgb(var(--zn-success));
  }

  .custom-stepper .label {
    font-weight: 700;
  }
</style>

Themed Steppers

Create themed steppers for different use cases or states.



<zn-stepper
  class="success-stepper"
  caption="Success State"
  steps="4"
  value="4"
  show-progress>
</zn-stepper>
<br />
<zn-stepper
  class="warning-stepper"
  caption="Warning State"
  steps="4"
  value="2"
  show-progress>
</zn-stepper>
<br />
<zn-stepper
  class="error-stepper"
  caption="Error State"
  steps="4"
  value="1"
  show-progress>
</zn-stepper>

<style>
  .success-stepper .step-progress {
    background-color: rgb(var(--zn-success));
  }
  .success-stepper .step {
    background-color: rgba(var(--zn-success), 0.3);
  }

  .warning-stepper .step-progress {
    background-color: rgb(var(--zn-warning));
  }
  .warning-stepper .step {
    background-color: rgba(var(--zn-warning), 0.3);
  }

  .error-stepper .step-progress {
    background-color: rgb(var(--zn-error));
  }
  .error-stepper .step {
    background-color: rgba(var(--zn-error), 0.3);
  }
</style>

Custom Height and Styling

Adjust the visual appearance of the stepper to match your design requirements.

<zn-stepper
  class="large-stepper"
  caption="Large Stepper"
  steps="4"
  value="2"
  show-progress>
</zn-stepper>

<style>
  .large-stepper .step-container {
    height: 20px;
  }

  .large-stepper .step {
    width: 24px;
    height: 24px;
    border-width: 4px;
  }

  .large-stepper .step-progress {
    height: 12px;
    top: 4px;
  }

  .large-stepper .step-line {
    height: 4px;
  }
</style>

Wizard Patterns

Using with Vertical Stepper

Combine horizontal and vertical steppers for comprehensive workflow navigation. The horizontal stepper shows overall progress while vertical steppers can show sub-steps within each main step. 



<zn-stepper
  label="Multi-Stage Process"
  caption="Stage 2: Configuration"
  steps="3"
  value="2"
  show-progress>
</zn-stepper>
<br /><br />
<zn-vertical-stepper caption="Database Setup" description="Configure database connection" first active></zn-vertical-stepper>
<zn-vertical-stepper caption="API Keys" description="Enter your API credentials" active></zn-vertical-stepper>
<zn-vertical-stepper caption="Deployment" description="Deploy to production" last></zn-vertical-stepper>

Progressive Disclosure

Use steppers to guide users through complex forms with progressive disclosure of information.


Steppers help break down complex multi-step processes into manageable chunks, improving user experience and reducing cognitive load. 

<zn-stepper
  id="disclosure-stepper"
  label="Registration Process"
  caption="Step 1 of 4"
  steps="4"
  value="1"
  show-progress>
</zn-stepper>
<br />
<p>Steppers help break down complex multi-step processes into manageable chunks, improving user experience and reducing cognitive load.</p>

Validation States

Combine steppers with validation feedback to show progress and validation status.


Please complete all required fields before proceeding to the next step. 
<zn-stepper
  label="Form Validation"
  caption="Step 2: Validation Required"
  steps="3"
  value="2"
  show-progress>
</zn-stepper>
<br />
<zn-alert color="warning" open>
  Please complete all required fields before proceeding to the next step.
</zn-alert>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.86/dist/components/stepper/stepper.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.86/dist/components/stepper/stepper.js';

To import this component using a bundler:

import '@kubex/zinc/dist/components/stepper/stepper.js';

Properties

Name Description Reflects Type Default
caption A descriptive label displayed above the stepper to indicate the current step or phase. string -
label An optional label displayed above the caption, typically used for the wizard or workflow name. string -
steps The total number of steps in the process. number -
value The current step position (0 to steps). Progress is calculated as value/steps. number -
show-progress When true, displays the step count (e.g., “2 / 5 steps”) next to the caption. boolean -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Parts

Name Description
step-container The container holding the progress line and steps.
step-line The background line showing the full step track.
step-progress The filled progress indicator showing completion.
steps The container for individual step markers.
step An individual step marker circle.
header The header container with caption and progress text.
caption The caption text element.
progress The progress count text (e.g., “2 / 5 steps”).
label The label text container.
info The label text element.

Learn more about customizing CSS parts.