Stepper - goobz22/goobs-frontend GitHub Wiki

Stepper Component

The Stepper component in goobs-frontend is a versatile component for displaying a sequence of steps in a process. It provides a visual representation of progress through a multi-step flow, such as a form wizard or a checkout process.

Importing the Component

To use the Stepper component in your project, import it from the goobs-frontend package:

import { CustomStepper, Step, StepLabel } from 'goobs-frontend';

Basic Usage

Here's a basic example of how to use the Stepper component:

import React from 'react';
import { CustomStepper, Step, StepLabel } from 'goobs-frontend';

const StepperExample: React.FC = () => {
  const steps = [
    { label: 'Step 1', stepNumber: 1, stepLink: '/step1', status: 'completed' },
    { label: 'Step 2', stepNumber: 2, stepLink: '/step2', status: 'active' },
    { label: 'Step 3', stepNumber: 3, stepLink: '/step3', status: 'inactive' },
  ];

  return (
    <CustomStepper steps={steps} activeStep={1}>
      {steps.map((step) => (
        <Step key={step.label}>
          <StepLabel>{step.label}</StepLabel>
        </Step>
      ))}
    </CustomStepper>
  );
};

export default StepperExample;

Props

The CustomStepper component accepts the following main props:

  • steps: Array of step objects, each containing:
    • stepNumber: number - The step number
    • label: string - The label for the step
    • stepLink: string - The link associated with the step
    • status: 'completed' | 'active' | 'error' | 'inactive' - The status of the step
    • statusLink: string (optional) - An alternative link for the step's status
  • activeStep: number - The current active step (0-based index)

Additionally, it supports all standard Material-UI Stepper props.

Features

  1. Customizable Steps: Supports defining custom steps with labels, links, and statuses.
  2. Visual Progress: Visually represents the current progress in a multi-step process.
  3. Step Status: Supports different statuses for steps (completed, active, error, inactive).
  4. Clickable Steps: Steps can be made clickable by providing step links.
  5. Accessibility: Includes proper ARIA attributes for screen readers.

Styling

The Stepper component uses Material-UI's styling system. You can customize its appearance using the sx prop or styled-components. Here's an example with custom styling:

import React from 'react';
import { CustomStepper, Step, StepLabel } from 'goobs-frontend';

const StyledStepperExample: React.FC = () => {
  const steps = [
    { label: 'Step 1', stepNumber: 1, stepLink: '/step1', status: 'completed' },
    { label: 'Step 2', stepNumber: 2, stepLink: '/step2', status: 'active' },
    { label: 'Step 3', stepNumber: 3, stepLink: '/step3', status: 'inactive' },
  ];

  return (
    <CustomStepper
      steps={steps}
      activeStep={1}
      sx={{
        '& .MuiStepLabel-root': {
          color: '#333',
        },
        '& .MuiStepIcon-root': {
          color: '#1976d2',
        },
        '& .MuiStepIcon-root.Mui-active': {
          color: '#4caf50',
        },
        '& .MuiStepIcon-root.Mui-completed': {
          color: '#4caf50',
        },
      }}
    >
      {steps.map((step) => (
        <Step key={step.label}>
          <StepLabel>{step.label}</StepLabel>
        </Step>
      ))}
    </CustomStepper>
  );
};

export default StyledStepperExample;

Advanced Usage

Controlled Stepper with Navigation

You can create a controlled Stepper with navigation buttons:

import React, { useState } from 'react';
import { CustomStepper, Step, StepLabel } from 'goobs-frontend';
import { Button, Box } from '@mui/material';

const ControlledStepperExample: React.FC = () => {
  const [activeStep, setActiveStep] = useState(0);
  const steps = [
    { label: 'Step 1', stepNumber: 1, stepLink: '/step1', status: 'active' },
    { label: 'Step 2', stepNumber: 2, stepLink: '/step2', status: 'inactive' },
    { label: 'Step 3', stepNumber: 3, stepLink: '/step3', status: 'inactive' },
  ];

  const handleNext = () => {
    setActiveStep((prevActiveStep) => prevActiveStep + 1);
  };

  const handleBack = () => {
    setActiveStep((prevActiveStep) => prevActiveStep - 1);
  };

  const handleReset = () => {
    setActiveStep(0);
  };

  return (
    <Box>
      <CustomStepper steps={steps} activeStep={activeStep}>
        {steps.map((step) => (
          <Step key={step.label}>
            <StepLabel>{step.label}</StepLabel>
          </Step>
        ))}
      </CustomStepper>
      <Box sx={{ display: 'flex', flexDirection: 'row', pt: 2 }}>
        <Button
          color="inherit"
          disabled={activeStep === 0}
          onClick={handleBack}
          sx={{ mr: 1 }}
        >
          Back
        </Button>
        <Box sx={{ flex: '1 1 auto' }} />
        {activeStep === steps.length - 1 ? (
          <Button onClick={handleReset}>Reset</Button>
        ) : (
          <Button onClick={handleNext}>Next</Button>
        )}
      </Box>
    </Box>
  );
};

export default ControlledStepperExample;

Stepper with Content

You can use the Stepper to guide users through content:

import React, { useState } from 'react';
import { CustomStepper, Step, StepLabel } from 'goobs-frontend';
import { Typography, Box, Button } from '@mui/material';

const StepperWithContentExample: React.FC = () => {
  const [activeStep, setActiveStep] = useState(0);
  const steps = [
    { label: 'Select campaign settings', content: 'Campaign settings content...' },
    { label: 'Create an ad group', content: 'Ad group content...' },
    { label: 'Create an ad', content: 'Ad creation content...' },
  ];

  const handleNext = () => {
    setActiveStep((prevActiveStep) => prevActiveStep + 1);
  };

  const handleBack = () => {
    setActiveStep((prevActiveStep) => prevActiveStep - 1);
  };

  return (
    <Box>
      <CustomStepper
        steps={steps.map((step, index) => ({
          label: step.label,
          stepNumber: index + 1,
          stepLink: `#step${index + 1}`,
          status: index === activeStep ? 'active' : index < activeStep ? 'completed' : 'inactive',
        }))}
        activeStep={activeStep}
      >
        {steps.map((step) => (
          <Step key={step.label}>
            <StepLabel>{step.label}</StepLabel>
          </Step>
        ))}
      </CustomStepper>
      <Typography sx={{ mt: 2, mb: 1 }}>{steps[activeStep].content}</Typography>
      <Box sx={{ display: 'flex', flexDirection: 'row', pt: 2 }}>
        <Button
          color="inherit"
          disabled={activeStep === 0}
          onClick={handleBack}
          sx={{ mr: 1 }}
        >
          Back
        </Button>
        <Box sx={{ flex: '1 1 auto' }} />
        <Button onClick={handleNext}>
          {activeStep === steps.length - 1 ? 'Finish' : 'Next'}
        </Button>
      </Box>
    </Box>
  );
};

export default StepperWithContentExample;

Accessibility

The Stepper component is designed with accessibility in mind:

  • It uses proper ARIA attributes to describe the structure and state of the stepper.
  • Each step is properly labeled for screen readers.
  • The component supports keyboard navigation.

To further enhance accessibility:

  1. Provide clear instructions on how to navigate through the steps.
  2. Ensure that any content associated with each step is also accessible.
  3. Consider adding ARIA live regions to announce step changes to screen readers.

Best Practices

  1. Clear Labels: Use concise and descriptive labels for each step.
  2. Logical Flow: Ensure the steps follow a logical and intuitive sequence.
  3. Visual Feedback: Clearly indicate the current active step and completed steps.
  4. Error Handling: Implement proper error handling for steps that may fail or require attention.
  5. Responsive Design: Ensure the stepper is usable on various device sizes, considering a vertical layout for mobile if necessary.

Performance Considerations

The Stepper component itself is generally lightweight, but consider the following for optimal performance:

  • For a large number of steps, consider implementing virtualization or pagination.
  • If step content is complex or data-heavy, implement lazy loading for step content.

Troubleshooting

  1. Steps Not Displaying Correctly: Ensure the steps prop is correctly formatted and all required properties are provided.
  2. Styling Issues: Check that custom styles are not conflicting with the component's internal styles.
  3. Navigation Problems: Verify that the activeStep prop is being updated correctly when navigating between steps.

By leveraging these features and following the best practices, you can effectively use the Stepper component in your goobs-frontend projects to create intuitive and user-friendly multi-step processes.

⚠️ **GitHub.com Fallback** ⚠️