Skip to content

Add <StepLabel /> labelPosition prop to Stepper to support label placement above, below, left, or right of StepIcon #46304

@swapnilnarhire

Description

@swapnilnarhire

Summary

The MUI Stepper component currently renders step labels below the icon when using alternativeLabel. There is no official or reliable way to reposition the labels above the icons. This feature request proposes adding a labelPosition prop to allow developers to control where the step label appears — for example: "top", "bottom", "left", or "right" — similar to what is available in other MUI components like Tabs or Timeline.

This would improve layout flexibility, support more real-world UI patterns (like onboarding flows or multi-step forms), and reduce the need for custom overrides or hacks.

A new prop called labelPosition should be added to the MUI Stepper component (or StepLabel) to control the position of the label relative to the step icon.

Developers should be able to choose from the following values:

"bottom" (default) – label appears below the icon

"top" – label appears above the icon

"left" – label appears to the left of the icon (for horizontal steppers)

"right" – label appears to the right of the icon (for horizontal steppers)

Examples

const percentage = Math.round(((activeStep + 1) / steps.length) * 100); {index === activeStep && ( <Typography variant="body2" sx={{ color: theme.palette.success.main }}> {percentage}% </Typography> )}
<Stepper activeStep={1} alternativeLabel labelPosition="top"> {steps.map((label) => ( <Step key={label}> <StepLabel>{label}</StepLabel> </Step> ))} </Stepper>
refer ant design [https://ant.design/components/steps]

Motivation

We are building a horizontal stepper interface for a multi-step form where the design requires the step labels to appear above the step icons for better clarity and alignment with the page title and layout.

However, MUI’s current implementation of alternativeLabel in the Stepper component only supports placing labels below the icon — with no official way to change that. Attempts to override this with custom CSS or sx styles are either brittle, break internal layout, or simply don't work due to the strict DOM structure.

Search keywords: StepLabel,Step,Stepper

Metadata

Metadata

Assignees

Labels

scope: stepperChanges related to the stepper.type: new featureExpand the scope of the product to solve a new problem.waiting for 👍Waiting for upvotes. Open for community feedback and needs more interest to be worked on.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions