Step Tracker

The ngs-step-tracker component displays the status of related steps without owning wizard navigation, validation, or routed content. Use it when users need to see which stages are completed, current, pending, blocked, or disabled.

Use Step Tracker for passive process status in cards, sidebars, drawers, setup summaries, payroll review flows, fulfillment states, and approval progress. Use ngs-stepper instead when users need next/previous navigation, linear validation, or step-owned content.

Bind activeIndex when the completed, current, and pending states should be derived from application state. Set item state explicitly for fixed statuses such as error or disabled. When activeIndex equals the number of items, all auto-state steps are completed.

Step Tracker supports vertical status lists and horizontal progress summaries. Items can use simple label and description inputs, or projected ngs-step-tracker-label and ngs-step-tracker-description elements when the copy needs richer markup. Completed and error indicators use NgStarter icons by default, can be configured globally with provideStepTracker, and can be overridden per tracker with ngsStepTrackerCompletedIcon and ngsStepTrackerErrorIcon templates.

Key Features:

Status-first steps: Mark each item as completed, current, pending, error, or disabled, or leave it as auto so the parent tracker resolves it from activeIndex.
Dynamic progress: Drive the current step with [(activeIndex)], setActiveIndex(), next(), and previous(). The final completed state is represented by an activeIndex equal to the item count.
Flexible content: Use label and description inputs for compact status lists, or project label and description elements for richer templates.
Vertical or horizontal: Show process status in a sidebar, card, drawer, or compact page header.
Configurable indicators: Override completed and error icons globally with provideStepTracker or locally with icon template directives.
Themeable tokens: Tune marker size, connector colors, status colors, and typography through --ngs-step-tracker-* variables.

Usage

Import the standalone pieces you use from the secondary entry point. Most applications need StepTracker and StepTrackerItem; add the label, description, icon directives, or provider only when the template uses those features.

import {
  provideStepTracker,
  STEP_TRACKER_CONFIG,
  StepTracker,
  StepTrackerCompletedIcon,
  StepTrackerErrorIcon,
  StepTrackerItem
} from '@ngstarter-ui/components/step-tracker';

Use compact label and description inputs for simple status lists. This keeps templates dense for business processes where each item is plain text and the state is known from application data.

<ngs-step-tracker>
  <ngs-step-tracker-item state="completed" label="Pay period & Employee"/>
  <ngs-step-tracker-item state="current" label="Total Hours" description="Review working hours"/>
  <ngs-step-tracker-item state="pending" label="Review payroll"/>
</ngs-step-tracker>

Bind activeIndex to resolve auto items dynamically from application state. Explicit states such as error and disabled stay fixed. Use an activeIndex equal to the item count when every auto-state step is finished. The component also exposes activeIndexChange, setActiveIndex(), next(), and previous() for imperative flows.

<ngs-step-tracker [(activeIndex)]="activeIndex">
  <ngs-step-tracker-item label="Pay period & Employee"/>
  <ngs-step-tracker-item label="Total Hours" description="Review working hours"/>
  <ngs-step-tracker-item state="error" label="Time off" description="Missing approval"/>
  <ngs-step-tracker-item label="Review payroll"/>
</ngs-step-tracker>

Project label and description elements when the item content needs a richer template. Projected content is useful for formatted labels, translated fragments, or descriptions that include inline structure instead of plain strings.

<ngs-step-tracker-item state="current">
  <ngs-step-tracker-label>Total Hours</ngs-step-tracker-label>
  <ngs-step-tracker-description>
    Review working hours before approval.
  </ngs-step-tracker-description>
</ngs-step-tracker-item>

Register completed and error indicator icon templates at the tracker level. These templates have the highest priority and override the default or globally configured icon names for the current tracker only.

<ngs-step-tracker orientation="horizontal">
  <ng-template ngsStepTrackerCompletedIcon>
    <ngs-icon name="fluent:shield-checkmark-24-regular"/>
  </ng-template>

  <ng-template ngsStepTrackerErrorIcon>
    <ngs-icon name="fluent:warning-24-regular"/>
  </ng-template>

  <ngs-step-tracker-item state="completed" label="Created"/>
  <ngs-step-tracker-item state="error" label="Documents"/>
</ngs-step-tracker>

Configure default indicator icon names globally with the Step Tracker environment provider. Use this when the application wants one consistent completed or error symbol across all trackers without repeating templates in every component.

import { provideStepTracker } from '@ngstarter-ui/components/step-tracker';

export const appConfig = {
  providers: [
    provideStepTracker({
      completedIconName: 'fluent:shield-checkmark-24-regular',
      errorIconName: 'fluent:warning-24-regular',
    }),
  ],
};

Step Tracker is a display component. It does not validate forms, render step panels, manage routing, or block progression. Use it for status visibility, and use Stepper or HeadlessStepper when the workflow itself needs navigation and validation.

Prop	Type	Default
ngs-step-tracker Container for status-only step tracker items. It owns orientation, activeIndex resolution, connector layout, and tracker-level icon template registration.	component	-
orientation Layout direction for the tracker. Use vertical for sidebars and compact cards, and horizontal for headers, summaries, and wide review surfaces.	'vertical' \| 'horizontal'	vertical
activeIndex Optional zero-based active step index. Auto-state items before it become completed, the matching item becomes current, and later items become pending. Use null to leave auto items pending, or set it to the item count to mark every auto-state item completed.	number \| null	null
ngs-step-tracker-item One status step inside a tracker. It renders the indicator, connector, label, description, and resolved visual state.	component	-
state Visual status for the step item. Use auto to let the parent activeIndex resolve completed/current/pending, or set a fixed status when the item should stay completed, current, pending, error, or disabled.	'auto' \| 'completed' \| 'current' \| 'pending' \| 'error' \| 'disabled'	auto
label Optional compact label input for the step item. Use projected label content instead when the label needs markup.	string	''
description Optional supporting text input for the step item. Use projected description content instead when the description needs markup.	string	''
ngs-step-tracker-label, [ngsStepTrackerLabel] Projected label content for richer step item templates. Used when the label input is empty.	component	-
ngs-step-tracker-description, [ngsStepTrackerDescription] Projected description content for richer step item templates. Used when the description input is empty.	component	-
[ngsStepTrackerCompletedIcon] Template directive that registers the icon rendered inside completed indicators for the current tracker. Overrides globally configured icon names.	directive	fluent:checkmark-16-filled
[ngsStepTrackerErrorIcon] Template directive that registers the icon rendered inside error indicators for the current tracker. Overrides globally configured icon names.	directive	fluent:error-circle-16-filled
provideStepTracker(config) Environment provider for global default completed and error indicator icon names. Use it in appConfig providers when every tracker should share the same default icons.	provider	-
STEP_TRACKER_CONFIG Injection token used by the provider to configure global indicator icon names. Advanced consumers can provide it directly when needed.	InjectionToken<StepTrackerConfig>	{ completedIconName: 'fluent:checkmark-16-filled', errorIconName: 'fluent:error-circle-16-filled' }

Event	Description
activeIndexChange	Emitted by the activeIndex model when the active step changes through two-way binding or StepTracker methods.

Method	Description
setActiveIndex(index: number)	Sets the active step index programmatically. Values are clamped to the valid range by the tracker.
next()	Moves activeIndex to the next step, clamped to the item count so the final step can become completed.
previous()	Moves activeIndex to the previous step, clamped to the first item.

Using this component in production?

Source code, templates, and commercial support

NgStarter includes source code, admin dashboard templates, and commercial support.

View pricing →Explore admin templates

Step Tracker

Usage

Source code, templates, and commercial support

Build the surrounding workflow