[Mantine UI Series] Stepper

[reboottime]

Overview

This article talks about Mantine UI Stepper component, including:

• its use cases from a product manager's view
• and its source code from a frontend developer's view

When and How Stepper Components Are Used

When user are in a complex flow of doing something, such as

• Progressive Data Input: When users need to input a substantial amount of information, breaking it down into smaller, manageable steps using a stepper can prevent overwhelming the user and improve the user experience.
• Complex Workflows: When the user needs to complete a series of distinct and interconnected steps to achieve a specific task.
• ... and more

In Front end Development domain and real world use cases:

• Certain steps are optional, enabling users to skip a stage within the stepper component.
• Other steps are enforced, ensuring users complete a stage within the stepper component.
• Certain steps may entail API interactions with backend services.
• In certain cases, there's a need to programmatically manage users' current step.
• And stepper component is customizable for developer users

[reboottime]

The Mantine UI Stepper component

Mantine UI Stepper component's API design has considered nearly all the usage scenarios mentioned earlier.

Good React practices for Developers

• How Mantine UI stepper expresses its connection with its subordinate components: Step and Completed

type StepperComponent = ForwardRefWithStaticComponents<
  StepperProps,
  {
    Step: typeof Step;
    Completed: typeof StepCompleted;
  }
>;

Stepper.Step = Step;
Stepper.Completed = StepCompleted;
Stepper.displayName = '@mantine/core/Stepper';

export type ForwardRefWithStaticComponents<
  Props extends Record<string, any>,
  Static extends Record<string, any>
> = ((props: Props) => React.ReactElement) &
  Static & {
    displayName: string;
  };

• How Mantine UI ensures that the Stepper's content contains valid subordinate component only
  

Utilizing the composition pattern enhances developer flexibility in structuring code, but poses challenges in enforcing expected usage.

To avoid unexpected content rendered inside of the Stepper, Mantine handles the concern in the following way

 const _children = convertedChildren.filter((child) => child.type === Step);
 const completedStep = convertedChildren.find((item) => item.type === StepCompleted);

  acc.push( cloneElement(item, {/**some other code**/}));

The side note, the child.type can either be a html tag name, or a reference to the type of a React component. See example bellow

import React from 'react';

const Title = () => <h1>Hello, Title!</h1>;

const App = () => {
  const htmlChild = <div>This is a div.</div>;
  const componentChild = <Title />;

  console.log('HTML child type:', htmlChild.type); // Outputs: "div"
  console.log('Component child type:', componentChild.type); // Outputs: Reference to the Title component
};

export default App;

• Extract the defaultProps derivation as a hook [Will be explained in a new issue)

[reboottime]

The Design Flaw of the Stepper Component

Lack of Consideration for Horizontal Mode

There are situations where you'd like to control the layout between Step content and the Stepper progress bar. Although the Stepper component provides two orientation modes: vertical and horizontal, the horizontal mode does not necessarily mean that the Mantine Stepper aligns its Step content on the right side, as shown bellow:

Given the source code of the Stepper, the solutions for achieving the desired UI layout are as follows:

• Introduce an Additional Wrapper: This can be achieved by introducing an extra wrapper element that serves as the content for each step within the content area.
• Adjust Box Layout with className: Alternatively, you can modify the Box layout by applying a specific className. This className will ensure that the child HTML elements of the Box align horizontally as a row.

Mental block on understanding allowStepClick and allowStepSelect Logic

The logical design of allowStepClick and allowStepSelect might not be immediately intuitive for developer users, unless they delve into the source code.

[reboottime]

References

1. Mantine UI, source code of Stepper
2. Carbon design system progress bar