Skip to content

Vertical Stepper with Descriptions

Dark Tailwind CSS vertical stepper with completed, current and upcoming states, step descriptions, a progress bar and Back / Mark as complete controls.

Also known as: vertical step progress, onboarding checklist steps, setup wizard steps, vertical timeline progress tracker

Tailwind CSS Steppers Responsive Dark #dark #onboarding #progress #responsive #stepper #steps

Vertical Stepper with Descriptions live demo

Open in new tab

Tailwind CSS code (HTML, CSS, JS)

A dark vertical stepper built with Tailwind CSS and a small vanilla JavaScript controller. Each step shows a numbered marker, a title, a status badge and a short description, with clear completed, current and upcoming states. It suits onboarding checklists, setup wizards, order tracking and application progress pages.

How it works

The root is section.vsd-stepper. The left column holds the heading and a progress card with a role="progressbar" track (data-vsd-bar) and an estimated time left. The right column is an ordered list (ol.vsd-list) of li.vsd-step items. Every step contains a round .vsd-dot marker, a .vsd-line connector to the next step, the title, three status badges and an empty .vsd-actions container.

All visual states come from one attribute: data-state on each li is complete, current or upcoming. Because each step has the group class, Tailwind variants such as group-data-[state=complete]:bg-violet-500 restyle the marker, swap the number for a check icon, brighten the title and show the matching badge. style.css adds the parts utilities cannot express: the connector fill that grows with transform: scaleY(), the pulsing halo on the current marker and the animated progress width driven by --vsd-progress.

On DOMContentLoaded the script reads data-vsd-current from the root, sets data-state and aria-current="step", and moves the data-vsd-controls buttons into the current step. "Mark as complete" advances (it reads "Finish setup" on the last step), "Back" returns, and after the last step the data-vsd-done panel appears with a "Start over" button. The counter, progress bar and remaining minutes (summed from each data-vsd-minutes) update on every change. Without JavaScript the states written in the markup still render correctly.

Customization

  • data-vsd-current="2" on .vsd-stepper: the 0-based index of the step in progress when the page loads.
  • data-vsd-minutes on each li.vsd-step: the time estimate used for the "Estimated time left" total.
  • violet-500, violet-400 and from-violet-500 to-fuchsia-400: replace with sky or emerald to change the accent of markers, buttons and the progress bar.
  • bg-slate-950 on the root: use bg-white with text-slate-700 for a light version.
  • md:grid-cols-[1fr_1.35fr] on the inner grid: remove it to show only the step list in a narrow sidebar.
  • vsd-pulse in style.css: lengthen the 2.4s duration or remove the animation for a calmer current step.
  • Add or remove li.vsd-step items freely; the script counts them, so "2 of 5 complete" adapts automatically.

Use cases

  • Onboarding checklists: new users see completed, current and upcoming setup steps with an estimated time left
  • Setup wizards: Back and Mark as complete buttons move people through each stage of configuration
  • Order tracking pages: customers follow progress down a vertical list with status badges per step
  • Application progress pages: applicants see a progress bar and a clear description for every stage

Accessibility

The steps form a real ordered list with aria-label="Setup steps", and the current item carries aria-current="step". Status badges are visible text, so screen readers hear "Completed", "In progress" or "Upcoming" with each title; decorative markers and connectors are aria-hidden. A sr-only live region announces the new current step after each click, focus stays on the button that was pressed, and every button has a visible focus outline. Pulse and fill animations stop under prefers-reduced-motion: reduce.

Usage notes

Several steppers can live on one page; each .vsd-stepper is initialized separately.

Vertical Stepper with Descriptions at a glance

Framework
Tailwind CSS
Code
HTML, CSS, JavaScript
JavaScript
Vanilla JavaScript, no jQuery
Dependencies
Tailwind CSS
Layout
Responsive, works on mobile, dark design
Category
Steppers
License
Free for personal and commercial use

Questions about this template

Can I use the Vertical Stepper with Descriptions code for free?

Yes. You can copy or download the code and use it in personal and commercial projects, including client work. No sign-up is needed. Reselling it as part of a component library or template collection is not allowed; see the license.

How do I add it to my website?

Load Tailwind CSS from a CDN (the links are under Requirements). Paste the HTML where the component should appear, add the CSS to your stylesheet and load the JavaScript before the closing </body> tag. Download HTML gives you a complete page with everything already linked.

Does it need jQuery or a JavaScript framework?

No. The script is plain vanilla JavaScript, so it works without jQuery, React or Vue. You can still use the markup inside those frameworks.

Does it work on mobile?

Yes. The layout adapts to small screens. Use the Mobile and Tablet buttons above the live demo to check it at phone and tablet width.

Requirements

Add these to your page (already included in the download):

  • <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

The Tailwind browser build is for prototyping. In production, compile Tailwind with its CLI or your bundler.

Vertical Stepper with Descriptions – Tailwind CSS steppers component screenshot
Vertical Stepper with Descriptions · Tailwind CSS Steppers

More Steppers

Horizontal Progress Stepper – Tailwind CSS steppers preview

Horizontal Progress Stepper

Tailwind CSS horizontal stepper with numbered circles, animated connector lines, completed/current/upcoming states and Back/Continue controls.

Tailwind CSS Steppers
Checkout Stepper – Bootstrap 5 steppers preview

Checkout Stepper

Bootstrap 5 four-step checkout with cart, shipping, payment and review steps, a progress bar, per-step validation, Back/Continue buttons and a live order summary.

Bootstrap 5 Steppers