# Progress Stepper

A vertical timeline for long-running work, such as an agent run or a deployment. Labels sit on one side of a single rail. Each marker shows its state: a green check for done, a spinning blue arc for in progress, and a dashed circle for not started. Sub-steps unfold under the active step and fold away when it completes. Hover the demo to pause the autoplay.

<demo-progress-stepper>



</demo-progress-stepper>

## Installation

```bash
npx shadcn-vue@latest add "https://nxui.geoql.in/r/progress-stepper.json"
```

## Usage

```vue
<script setup lang="ts">
  import { ref } from 'vue';
  import ProgressStepper from '~/components/ui/progress-stepper/ProgressStepper.vue';
  import type { ProgressStep } from '~/components/ui/progress-stepper/types';

  const steps: ProgressStep[] = [
    { id: 'plan', title: 'Resolution Planning' },
    {
      id: 'implement',
      title: 'Implementation',
      children: [
        { id: 'configure', title: 'Configure Solution' },
        { id: 'apply', title: 'Apply Changes' },
      ],
    },
    { id: 'summary', title: 'Final Summary' },
  ];

  const current = ref(1);
  const currentChild = ref(0);
</script>

<template>
  <ProgressStepper
    v-model:current="current"
    v-model:current-child="currentChild"
    :steps="steps"
  />
</template>
```

Statuses come from `current` and `current-child` by default. Set `status` on a step or sub-step to override them, for example to show a step that was skipped.

## Props

<table>
<thead>
  <tr>
    <th>
      Prop
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        steps
      </code>
    </td>
    
    <td>
      <code>
        ProgressStep[]
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Top-level steps. Each step can have <code>
        children
      </code>
      
       sub-steps.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        current
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0
      </code>
    </td>
    
    <td>
      <code>
        v-model
      </code>
      
      . Index of the active step. <code>
        steps.length
      </code>
      
       marks every step done.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        current-child
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0
      </code>
    </td>
    
    <td>
      <code>
        v-model
      </code>
      
      . Index of the active sub-step inside the active step.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        align
      </code>
    </td>
    
    <td>
      <code>
        'right' | 'left'
      </code>
    </td>
    
    <td>
      <code>
        'right'
      </code>
    </td>
    
    <td>
      <code>
        right
      </code>
      
       puts labels left of the rail. <code>
        left
      </code>
      
       puts them right of the rail.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        show-step-label
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Shows "Step N" under steps that have no <code>
        description
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        class
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        ''
      </code>
    </td>
    
    <td>
      Extra classes for the root list.
    </td>
  </tr>
</tbody>
</table>

## Slots

<table>
<thead>
  <tr>
    <th>
      Slot
    </th>
    
    <th>
      Props
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        title
      </code>
    </td>
    
    <td>
      <code>
        { step }
      </code>
    </td>
    
    <td>
      Replaces a top-level step title.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      <code>
        { step }
      </code>
    </td>
    
    <td>
      Replaces the line under a top-level title.
    </td>
  </tr>
</tbody>
</table>

## Accessibility

- Renders an ordered list. The active step and sub-step get `aria-current="step"`.
- Each step announces its state as "completed", "in progress" or "not started".
- The spinner and the check animation stop when the user prefers reduced motion.