ng-hub-ui-stepper

A flexible, customizable, and accessible stepper component for Angular 21+. Perfect for multi-step forms, wizards, and guided user experiences with a focus on developer experience and modern standards.

[!IMPORTANT] This version (21.2.0) is built for Angular 21 and uses the new Signals architecture.

🧩 Library Family ng-hub-ui

This library is part of the ng-hub-ui ecosystem:

• ng-hub-ui-accordion
• ng-hub-ui-avatar
• ng-hub-ui-board
• ng-hub-ui-breadcrumbs
• ng-hub-ui-calendar
• ng-hub-ui-modal
• ng-hub-ui-paginable
• ng-hub-ui-portal
• ng-hub-ui-stepper
• ng-hub-ui-utils

Table of Contents

• Features
• Installation
• Usage (Quick Start)
• Examples
  • Linear Stepper
  • Custom Navigation
  • Custom Buttons
• API Reference
  • StepperComponent
  • StepComponent
  • Directives
  • Interfaces
• Styling
• Contributing
• License

Features

• 🚀 Angular 21+ Built-in: Uses Signals and new control flow syntax.
• 🎨 Highly Customizable: Easy to theme via CSS variables and custom templates.
• ♿ Accessible: Proper ARIA roles and keyboard navigation.
• 🔢 Multi-layout: Supports Vertical, Sidebar, and RTL modes.
• 🔄 Smooth Transitions: Built-in CSS animations.
• 🧩 Flexible Controls: Use default buttons or project your own.

Installation

npm install ng-hub-ui-stepper

Usage (Quick Start)

Import the StepperModule in your module/component:

import { StepperModule } from 'ng-hub-ui-stepper';

@Component({
  standalone: true,
  imports: [StepperModule],
  // ...
})
export class YourComponent { }

In your template:

<hub-stepper>
  <hub-step title="Account Setup">
    <h3>Welcome!</h3>
    <p>Setup your account details here.</p>
  </hub-step>

  <hub-step title="Personal Info">
    <h3>Profile Data</h3>
    <p>Tell us more about yourself.</p>
  </hub-step>

  <hub-step title="Review">
    <h3>Save & Finalize</h3>
    <p>Ready to go?</p>
  </hub-step>
</hub-stepper>

Examples

Linear Stepper

Control navigation by enabling/disabling steps programmatically.

<hub-stepper (completed)="onFinish()">
  <hub-step title="Step 1">
    <!-- Step 1 Content -->
  </hub-step>

  <hub-step title="Step 2" [disabled]="!isStep1Valid()">
    <!-- Step 2 Content -->
  </hub-step>
</hub-stepper>

Custom Navigation

Provide your own navigation template using the stepperNavTpt property.

<hub-stepper>
  <nav *stepperNav="let steps = steps; let currentIndex = currentIndex" class="my-custom-nav">
     @for (step of steps; track step; let i = $index) {
       <button
         [class.active]="i === currentIndex"
         (click)="goTo(i)">
         {{ step.title() }}
       </button>
     }
  </nav>

  <hub-step title="A">...</hub-step>
  <hub-step title="B">...</hub-step>
</hub-stepper>

Custom Buttons

Project your own buttons to override the default footer.

<hub-stepper>
  <hub-step>...</hub-step>

  <button previousButton class="btn-back">Go back</button>
  <button nextButton class="btn-next">Next step</button>
  <button submitButton class="btn-done">Complete</button>
</hub-stepper>

API Reference

StepperComponent (hub-stepper)

| Input | Type | Default | Description | |---|---|---|---| | backLabel | string | 'Back' | Label for the back button. | | continueLabel | string | 'Continue' | Label for the continue button. | | submitLabel | string | 'Submit' | Label for the submit button. | | options | StepperOptions | {} | Visual and layout configuration. |

| Output | Type | Description | |---|---|---| | completed | EventEmitter<void> | Emitted when the last step is completed. | | previousStep | EventEmitter<number> | Emitted when moving back. Passes the new index. | | nextStep | EventEmitter<number> | Emitted when moving forward. Passes the new index. |

StepComponent (hub-step)

| Input | Type | Default | Description | |---|---|---|---| | title | string | optional | Text displayed in navigation. | | disabled | boolean | false | Prevents navigation to this step. |

Directives

• nextButton: Apply to any button to use it as the "next" control.
• previousButton: Apply to any button to use it as the "back" control.
• submitButton: Apply to any button to use it as the "submit" control.
• stepperNav: Mark a template to be used as custom navigation.

Interfaces

StepperOptions

interface StepperOptions {
  layout?: 'vertical' | 'sidebar';
  rtl?: boolean;
}

Styling

Customize the component using CSS variables. For a complete list of available tokens, see the CSS Variables Reference.

.my-stepper {
  --hub-stepper-primary-color: #009ef7;
  --hub-stepper-surface-color: #ffffff;
  --hub-stepper-gap: 1.5rem;
}

Contributing

We welcome contributions! Please follow our Commit Guidelines.

1. Fork the repo.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes.
4. Push to the branch.
5. Create a Pull Request.

Support

If you find this project helpful, consider supporting its development:

License

This project is licensed under the MIT License - see the LICENSE file for details.