Migrating from UISteps to HighRise Progress Steps

This guide will help you migrate from the ghl-ui Steps component to the new HighRise Progress Steps component.

Component Implementation Changes

Import Changes

- import { UISteps, UIStep } from '@gohighlevel/ghl-ui'
+ import { HLProgressSteps } from '@platform-ui/highrise'

Breaking Changes

ARCHITECTURE CHANGES

The following architectural changes have been made:

1. Component Structure:

   • Old: Used separate UISteps and UIStep components
   • New: Single HLProgressSteps component with data-driven steps
   • Migration requires converting child components to array structure

2. Status System:

   • Old: Limited status options ('wait', 'error', 'finish', 'process')
   • New: Enhanced status system ('complete', 'current', 'warning', 'error', default)
   • More granular control over individual step status

3. Step Configuration:

   • Old: Used slots for step content
   • New: Uses structured step objects with title, subtitle, and status

PROP CHANGES

1. New Required Props:

   • id: Required for accessibility
   • steps: Array of step objects

2. Changed Props:

   • current → Use status: 'current' in step object
   • description → subtitle in step object
   • status → Individual status per step

3. New Props:

   • vertical: Boolean for vertical layout (unchanged)
   • className: Additional CSS classes
   • Step object properties:
     • renderIcon: Custom icon function
     • popoverProps: Popover configuration
     • count: Custom step number

4. Removed Props:

   • Individual UIStep props (now part of step object)

Examples

Basic Steps

- <UISteps :current="currentStep">
-   <UIStep
-     title="Create Account"
-     description="Set up your account"
-   />
-   <UIStep
-     title="Verify Email"
-     description="Confirm your email address"
-   />
-   <UIStep
-     title="Complete Profile"
-     description="Add your personal information"
-   />
-   <UIStep
-     title="Finish"
-     description="Review and submit"
-   />
- </UISteps>

+ <HLProgressSteps
+   id="onboarding-steps"
+   :steps="[
+     {
+       title: 'Create Account',
+       subtitle: 'Set up your account',
+       status: 'complete'
+     },
+     {
+       title: 'Verify Email',
+       subtitle: 'Confirm your email address',
+       status: 'complete'
+     },
+     {
+       title: 'Complete Profile',
+       subtitle: 'Add your personal information',
+       status: 'current'
+     },
+     {
+       title: 'Finish',
+       subtitle: 'Review and submit'
+     }
+   ]"
+ />

Interactive Steps

<template>
  <HLProgressSteps id="interactive-steps" :steps="steps" @update:step="handleStepClick" />
</template>

<script setup>
import { ref, computed } from 'vue'
import { HLProgressSteps } from '@platform-ui/highrise'

const currentStep = ref(1)

const steps = computed(() => [
  {
    title: 'Step 1',
    subtitle: 'First step description',
    status: currentStep.value > 0 ? 'complete' : 'current',
    className: 'clickable-step',
  },
  {
    title: 'Step 2',
    subtitle: 'Second step description',
    status: currentStep.value > 1 ? 'complete' : currentStep.value === 1 ? 'current' : 'default',
    className: 'clickable-step',
  },
  {
    title: 'Step 3',
    subtitle: 'Third step description',
    status: currentStep.value === 2 ? 'current' : 'default',
    className: 'clickable-step',
  },
])

const handleStepClick = index => {
  currentStep.value = index
}
</script>

<style>
.clickable-step {
  cursor: pointer;
}
.clickable-step:hover {
  opacity: 0.9;
}
</style>

Vertical Steps with Icons

<template>
  <HLProgressSteps id="vertical-steps" :steps="steps" vertical />
</template>

<script setup>
import { HLProgressSteps } from '@platform-ui/highrise'
import { UserIcon, MailIcon, CheckIcon } from '@gohighlevel/ghl-icons/24/outline'

const steps = [
  {
    title: 'Account Created',
    subtitle: 'Your account has been created successfully',
    status: 'complete',
    renderIcon: () => h(UserIcon),
  },
  {
    title: 'Verification',
    subtitle: 'Please verify your email',
    status: 'warning',
    renderIcon: () => h(MailIcon),
  },
  {
    title: 'Completed',
    subtitle: 'All steps are completed',
    status: 'current',
    renderIcon: () => h(CheckIcon),
  },
]
</script>

Type Definitions

interface HLProgressStepProps {
  id?: string
  className?: string
  count?: number
  last?: boolean
  popoverProps?: boolean | PopoverProps
  renderIcon?: () => VNodeChild | undefined
  subtitle?: string
  status?: 'complete' | 'current' | 'warning' | 'error' | 'default'
  vertical?: boolean
  title: string
}

Best Practices

1. Always provide unique id props for accessibility
2. Use clear and concise titles and subtitles
3. Implement proper status management
4. Consider using icons for visual clarity
5. Use clickable steps when navigation is needed
6. Keep step content concise
7. Use vertical layout for complex steps
8. Implement proper error handling
9. Consider mobile responsiveness
10. Follow accessibility guidelines

Additional Notes

1. The component provides built-in responsive design
2. Enhanced status visualization
3. Support for custom icons
4. Improved accessibility features
5. Built-in click handling
6. Consistent styling with HighRise
7. Support for RTL layouts
8. Better mobile support
9. Popover support for additional content
10. Integration with other HighRise components