Angular Timeline & Progress Steps | ng-hub-ui-milestones

Angular timeline and progress-steps component: vertical or horizontal, fully customizable nodes, content inside and beside each step, themed with CSS variables.

Last updated Sep 6, 2026

Overview

Why teams search for this library

Choose this Angular timeline component when you need a presentational progress tracker — onboarding flows, order tracking, roadmaps — with custom nodes and both vertical and horizontal layouts.

Install

npm install ng-hub-ui-milestones

Jump to

Ideal for

  • onboarding flows
  • order tracking
  • roadmaps
  • process steps

About milestones

ng-hub-ui-milestones lays out a series of steps connected by a rail, vertically or horizontally. Each node is fully customizable — number, icon, avatar or any markup inside the circle, plus rich content beside it — and every colour, size and connector is a CSS variable, so it re-themes at runtime.

Feature guides

Orientation

Lay the timeline out vertically (the default, ideal for wizards and activity feeds) or horizontally (progress steps across the top of a page). Nodes are numbered automatically in DOM order.

Examples:
Vertical timeline

Vertical timeline

Information

Account details captured and verified.

Shipping

Delivery address confirmed.

Payment

Enter your payment method to continue.

Review

Place the order once everything looks right.

Horizontal progress steps

Horizontal progress steps

Information

Account verified.

Shipping

Address confirmed.

Payment

In progress.

Review

Last step.

Node states

Each `hub-milestone` carries a `state` — complete, active, pending or error — that drives the node and connector colors. The `label` input renders fallback text inside the circle.

Examples:
Node states

Node states

Complete

A finished step.

Active

The current step, highlighted with a ring.

Error

Something needs attention here.

Pending

Not started yet.

Custom nodes & theming

Project any content into the circle with `<ng-template hubMilestoneNode>` (numbers, icons, emoji, avatars), override a single node with `color`, or re-theme the whole timeline through `--hub-milestone-*` CSS variables.

Examples:
Custom nodes & per-node color

Custom nodes & per-node color

Drafted

Article written and saved.

Reviewed

Approved by the editor.

Publishing

Going live across channels.

Promotion

Scheduled for next week.

CSS-variable theming

CSS-variable theming

Kickoff

Project scoped and approved.

Build

Core features shipped.

Launch

Rolling out to production.

Animation

When the timeline scrolls into view it completes its accent trail up to the active node — on by default and configurable globally with `provideHubMilestones`. Add `[pulse]` to make the active node emit a soft wave. Both animations respect `prefers-reduced-motion`.

Examples:
Horizontal with active pulse

Horizontal with active pulse

Ordered

Payment received.

Packed

Ready to ship.

In transit

Out for delivery now.

Delivered

Arriving soon.

Key features

Recent changes

Version 22.3.3 - 9/6/26, 12:00 AM

fixed: The documentation no longer denies the ng-hub-ui-utils dependency the package requires. Both READMEs advertised zero runtime dependencies and an install line naming this package alone, while peerDependencies has demanded ng-hub-ui-utils since 22.3.0, so a reader installing by hand ended up with an application that cannot resolve resolveHubAccent. The install block now names both packages and states the peer range.

fixed: hubMilestoneNode is described as what it is: an attribute directive. Calling it structural set the wrong expectation about where its content appears. It only tags a template, and hub-milestone is what renders it inside the circle.

fixed: HUB_MILESTONES_CONFIG is in the API reference. The token is exported from public-api.ts and is the only way to read the resolved application defaults, yet neither README named it.

fixed: The Styling section documents the SCSS the package ships. The theming mixin and the styles entry point have been published since 22.2.0 with no trace in either README, leaving the one-call theming path visible only to whoever read the changelog.

Version 22.3.2 - 9/1/26, 12:00 AM

changed: The homepage in the manifest points at this library's own documentation page rather than at the site root. It is the link a registry shows beside the package and the one a reader clicks from it, and landing on a front page they then have to search is a worse answer than landing on the reference for the package they were already looking at. Metadata only — no code, no types, no styles change, and nothing a consumer imports is affected.

Version 22.3.1 - 8/8/26, 12:00 AM

fixed: Documentation links now point at the canonical localized URLs. The README linked to https://hubui.dev/<path> with no locale prefix and no trailing slash, and both forms are 301-redirected, so every reader arriving from npm or GitHub landed on a redirect instead of the canonical page.

Version 22.3.0 - 7/28/26, 12:00 AM

changed: Accent resolution now imports the canonical resolveHubAccent from ng-hub-ui-utils. The private copy under src/lib/shared/resolve-hub-accent.ts has been deleted in favour of the single, tested implementation shared family-wide. Behaviour is identical (the copy had not diverged): a bareword resolves to var(--hub-sys-color-<name>, <name>), a literal colour passes through unchanged, an empty value yields null.

added: NEW peer dependency: ng-hub-ui-utils >=22.7.0. Consumers must have ng-hub-ui-utils installed alongside this library (it is where resolveHubAccent lives). Users installing via ng add ng-hub-ui get it automatically; manual installs need npm i ng-hub-ui-utils.

Version 22.2.1 - 7/28/26, 12:00 AM

fixed: Each milestone exposes role=listitem and the active node announces aria-current=step, completing the list semantics the container already declared.

Version 22.2.0 - 7/7/26, 12:00 AM

added: hub-milestones-theme(...) SCSS mixin — one-call token theming for <hub-milestones>, covering the full --hub-milestone-* surface: completed steps ($node-color, $node-text, $node-size, $node-font-size, $connector-bg, $connector-thickness), upcoming steps ($pending-bg, $pending-border, $pending-color, $connector-pending-bg), the error state ($error-bg), the step body ($body-color, $body-muted) and layout ($gap, $spacing). Every parameter is null-defaulted and additive.

changed: Packaging — the library now ships its SCSS at /styles. src/lib/styles is emitted to dist/milestones/styles, exposing hub-milestones-theme as a first-class package entry: @use 'ng-hub-ui-milestones/styles' as *;

Version 22.1.0 - 7/7/26, 12:00 AM

changed: <hub-milestone> color accepts ANY colour. On top of the built-in semantic accents, the input now also accepts a registered custom accent and a literal colour (#ff0000, rgb(...), oklch(...), a CSS named colour), resolved through the shared resolveHubAccent resolver: a bareword becomes var(--hub-sys-color-<name>, <name>); a literal is used as-is. Built-in colours are unchanged.

changed: Internal — host bindings moved to the host metadata object. @HostBinding / @HostListener decorators were replaced by the host object in the component and directive metadata (Angular style guide). No public API or behaviour change.

Version 22.0.3 - 6/25/26, 12:00 AM

changed: Widened the Angular peer dependency range from ^22.0.0 to >=21.0.0, so the library installs on Angular 21 projects as well, aligning it with the rest of the ng-hub-ui family. No code changes.

Version 22.0.2 - 6/25/26, 12:00 AM

added: Viewport reveal — when a <hub-milestones> scrolls into view it plays a one-shot animation, filling the accent trail from the first node up to the active node. On by default; set it globally with provideHubMilestones({ reveal: false }) or per instance with [reveal]. Tunable via --hub-milestone-reveal-duration / --hub-milestone-reveal-stagger, SSR-safe and disabled under prefers-reduced-motion.

added: provideHubMilestones() provider and HubMilestonesConfig for app-wide defaults, plus the [pulse] input on <hub-milestones> — an opt-in soft wave on the active node whose colour follows the node accent and is overridable via --hub-milestone-pulse-color / --hub-milestone-pulse-duration / --hub-milestone-pulse-spread.

fixed: Connectors now reach from node to node: the connector is absolutely positioned and always spans node edge to next-node edge, in both orientations. Its colour follows the theme accent (--hub-milestone-node-color) instead of the hardcoded purple-to-orange gradient, the accent trail stops at the active node so the timeline reads as a real progress indicator, and layout, connectors and the reveal flip correctly under dir='rtl'.

Version 22.0.1 - 6/25/26, 12:00 AM

fixed: Design-token consistency pass: aligned inline fallback defaults with the canonical ng-hub-ui-ds values and routed hardcoded literals (z-index, font-weight, line-height, radii and theme-aware colours) through their --hub-sys-* / --hub-ref-* tokens, so they follow the active theme. No visual change when the ds tokens are loaded.

Version 22.0.0 - 6/17/26, 12:00 AM

changed: Aligned with Angular 22. README documentation standardized.

Version 21.0.0 - 6/14/26, 12:00 AM

added: Initial release: hub-milestones container (vertical / horizontal orientation, auto-numbered nodes) and hub-milestone node with complete/active/pending/error states.

added: Per-node color override, label fallback and custom in-circle content via the hubMilestoneNode template directive.

added: Full --hub-milestone-* CSS-variable theming for node, connector, states and spacing.

Related libraries

ng-hub-ui-stepper ng-hub-ui-nav ng-hub-ui-panels

Frequently asked questions

How do I build a timeline component in Angular?

Install ng-hub-ui-milestones and give HubMilestonesComponent a list of steps. It draws the rail and the nodes and marks each step's state, which makes it a fit for order tracking, onboarding flows and project roadmaps where the timeline is presentational rather than interactive.

Can the timeline be horizontal instead of vertical?

Yes. HubMilestonesOrientation switches the whole layout between vertical and horizontal with one input, and the same step content works in both — useful when the timeline is a sidebar on desktop and a horizontal strip on narrow screens.

How do I put custom content inside each timeline node?

HubMilestoneNodeDirective replaces the circle at each step, so a node can be a number, an icon, an avatar or any markup you want. Rich content can also sit beside the node, which is how you attach dates, descriptions or actions to a step.

What is the difference between a timeline and a stepper in Angular?

A timeline shows progress that has already happened or is planned, and the user does not drive it. A stepper guides someone through a form or a wizard, validating each step. Use ng-hub-ui-milestones to display a sequence and ng-hub-ui-stepper when the user must advance through it.