[stepper] Proper support for vertical alternativeLabel

[silviuaavram]

• I have followed (at least) the PR section of the contributing guide.

Properly support vertical orientation with alternativeLabel.

Move the steps and the content to the opposite side using variant overrides. Another option would have been to ignore the alternativeLabel prop when vertical orientation is used, and show a warning. But supporting it visually without showing a broken UI seems to be better.

Before	After

[code-infra-dashboard]

Deploy preview

• docs/data/material/components/steppers/steppers.md

Bundle size

Bundle	Parsed size	Gzip size
@mui/material	🔺+1.12KB(+0.22%)	🔺+101B(+0.07%)
@mui/lab	0B(0.00%)	0B(0.00%)
@mui/private-theming	0B(0.00%)	0B(0.00%)
@mui/system	0B(0.00%)	0B(0.00%)
@mui/utils	0B(0.00%)	0B(0.00%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.

[Copilot]

Pull request overview

This PR extends Material UI Stepper styling so alternativeLabel works properly when the Stepper is in vertical orientation, primarily by mirroring/alignment adjustments across Step, StepLabel, StepConnector, and StepContent.

Changes:

• Add vertical + alternativeLabel styling variants to align the stepper/labels/connectors for the mirrored vertical layout.
• Update StepContent to consume alternativeLabel from StepperContext and apply right-aligned spacing/border styles when enabled.
• Refine Step variants to differentiate horizontal vs vertical alternativeLabel layout behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/mui-material/src/Stepper/Stepper.js	Adds a vertical+alternativeLabel variant to adjust cross-axis alignment.
packages/mui-material/src/StepLabel/StepLabel.js	Adds vertical+alternativeLabel variants to flip label layout and adjust spacing/alignment.
packages/mui-material/src/StepContent/StepContent.js	Adds alternativeLabel styling for mirrored vertical content and threads alternativeLabel into ownerState.
packages/mui-material/src/StepConnector/StepConnector.js	Splits alternativeLabel handling by orientation and adds vertical+alternativeLabel margins.
packages/mui-material/src/Step/Step.js	Adds new variants for horizontal (non-alt) and vertical (alt) layouts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[siriwatknp]

It should be either in the docs demo or regression to appear in Argos.

[siriwatknp]

The alternativeLabel JSDoc on Stepper.d.ts:18 still says "If set to true and orientation is horizontal, then the step label will be positioned under the icon." Since this PR generalizes the prop to vertical, please update the JSDoc and re-run pnpm proptypes so the docs reflect the new behavior.

[siriwatknp]

this is strange. it's either variant or classname, not both.

{
      props: { orientation: 'vertical', alternativeLabel: true },
      style: { flexDirection: 'row-reverse' }
}

or

 …base styles
  [`&.${stepLabelClasses.alternativeLabel}`]: {
    flexDirection: 'row-reverse',
  }

[siriwatknp]

Minor comment on the variants vs class selector. Also, the structure of the StepConnector is different (it's within li which is correct markup), do you plan to update other demo in a separate PR?

no objection, but the support of alternativeLabel like this I could not have think of a use case:

[siriwatknp]

and

[ZeeshanTamboli]

Perhaps not related to this PR, but it seems wrong that the Transition section is under the Vertical Stepper section in the docs.

[silviuaavram]

and

Related to this, it's the text-align property. Not sure what to add instead, maybe leave it to the user? My main objective with this PR is to make the vertical+alernativeLabel example not look like we haven't even considered it. As mentioned above, the alternative would have been to thrown an error and not change anything. @siriwatknp

[mj12albert]

Related to this, it's the text-align property.

Codex also flagged this:

StepContent sets textAlign: 'right' on the content root when alternativeLabel is true. That affects all nested content, including paragraphs, forms, and buttons, not just the stepper placement.

Maybe we could set text-align in the demo instead of the component? It would a bit better for users to set their own text-align as needed, rather than fight text align right if they didn't want it

[mj12albert]

Codex finding:

packages/mui-material/src/Stepper/Stepper.js makes vertical steppers a column, but packages/mui-material/src/Step/Step.js#L68 applies flex: 1 to every alternativeLabel step regardless of orientation. In a height-constrained vertical stepper – e.g. fixed height, a flex/grid parent, a drawer/sidebar layout – this makes steps grow and distribute vertically, unlike regular vertical steppers. Scope that rule to { orientation: 'horizontal', alternativeLabel: true }.

[mj12albert]

Looks good ~