Mantine SelectStepper Component

Overview

This component is created on top of the Mantine library. It requires Mantine 9.x and React 19.

The Mantine SelectStepper is a Mantine-based React component that provides an elegant way to select from a list of options through a stepper interface. Users can navigate forward and backward through items using action buttons, with support for keyboard navigation, infinite looping, disabled items, and smooth animations. Built with TypeScript and fully integrated with Mantine's Styles API, it offers extensive customization options including custom icons, animation timing, viewport width, and border styling.

[!note]

→ Demo and Documentation → Youtube Video → More Mantine Components

Key Features

• Swipe/Touch gestures — native pointer events for mobile navigation
• Vertical orientation — render as a vertical stepper with up/down arrows
• Imperative API — controlRef with next(), prev(), reset(), navigateTo() methods
• Size prop — control ActionIcon size (xs through xl)
• Animation callbacks — onStepStart and onStepEnd for transition synchronization
• Gradient variant — gradient-styled navigation buttons
• Full keyboard navigation — Arrow keys with automatic disabled item skipping
• Loop mode — infinite cycling through options
• Styles API — full Mantine Styles API integration with 10 style targets
• Responsive props — viewWidth, viewHeight, size, orientation adapt to breakpoints via Mantine's StyleProp
• Accessible — ARIA spinbutton role, live regions, labeled buttons

Installation

npm install @gfazioli/mantine-select-stepper

or

yarn add @gfazioli/mantine-select-stepper

After installation import package styles at the root of your application:

import '@gfazioli/mantine-select-stepper/styles.css';

You can also import styles within a CSS layer:

import '@gfazioli/mantine-select-stepper/styles.layer.css';

Usage

import { SelectStepper } from '@gfazioli/mantine-select-stepper';

function Demo() {
  return <SelectStepper data={['React', 'Vue', 'Angular']} />;
}

Imperative API

import { useRef } from 'react';
import { SelectStepper, type SelectStepperRef } from '@gfazioli/mantine-select-stepper';

function Demo() {
  const controlRef = useRef<SelectStepperRef>(null);

  return (
    <>
      <SelectStepper
        controlRef={controlRef}
        data={['React', 'Vue', 'Angular']}
      />
      <button onClick={() => controlRef.current?.next()}>Next</button>
      <button onClick={() => controlRef.current?.reset()}>Reset</button>
    </>
  );
}

Sponsor

Your support helps me:

• Keep the project actively maintained with timely bug fixes and security updates
• Add new features, improve performance, and refine the developer experience
• Expand test coverage and documentation for smoother adoption
• Ensure long‑term sustainability without relying on ad hoc free time
• Prioritize community requests and roadmap items that matter most

Open source thrives when those who benefit can give back—even a small monthly contribution makes a real difference. Sponsorships help cover maintenance time, infrastructure, and the countless invisible tasks that keep a project healthy.

Your help truly matters.

💚 Become a sponsor today and help me keep this project reliable, up‑to‑date, and growing for everyone.

---

https://github.com/user-attachments/assets/d430dd46-2da5-46e3-8dcd-73f666f8c6fe