Migrating from ghl-ui Spin to HighRise Spin

This guide helps you migrate from the legacy UISpin component to the new HLSpin component. The new component provides enhanced TypeScript support, improved accessibility, and better integration with the HighRise design system.

Component Implementation Changes

Import Changes

- import { UISpin } from '@gohighlevel/ghl-ui'
+ import { HLSpin } from '@platform-ui/highrise'

Basic Usage Changes

<!-- Old usage -->
- <UISpin size="medium" />

<!-- New usage -->
+ <HLSpin id="loading-spinner" size="md" />

Props Changes

Required Props

ghl-ui Prop	HighRise Prop	Notes
-	id	New required prop for accessibility

Modified Props

ghl-ui Prop	HighRise Prop	Notes
size	size	Values changed: 'small'→'sm', 'medium'→'md', 'large'→'lg'

Size Mapping

ghl-ui Size	HighRise Size
'small'	'sm'
'medium'	'md'
'large'	'lg'
number	number

Slots Changes

ghl-ui Slot	HighRise Slot	Notes
-	description	New slot for loading description
-	icon	New slot for custom loading icon

Examples

Basic Spinner

<!-- Old -->
<template>
  <UISpin size="medium" />
</template>

<!-- New -->
<template>
  <HLSpin id="basic-spinner" size="md" />
</template>

<script setup>
import { HLSpin } from '@platform-ui/highrise'
</script>

With Content Overlay

<template>
  <HLSpin id="content-spinner" :show="isLoading">
    <div class="content">
      <h3>User Profile</h3>
      <p>This content will be overlaid with a spinner when loading</p>
      <p>The content remains visible but is dimmed during loading</p>
    </div>
  </HLSpin>
</template>

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

const isLoading = ref(true)
</script>

With Description

<template>
  <HLSpin id="description-spinner" size="lg">
    <template #description> Loading your data... </template>
    <div class="content">
      <p>Content being loaded...</p>
    </div>
  </HLSpin>
</template>

With Custom Icon

<template>
  <HLSpin id="custom-icon-spinner">
    <template #icon>
      <HLIcon size="34px">
        <Loading01Icon />
      </HLIcon>
    </template>
  </HLSpin>
</template>

<script setup>
import { HLSpin, HLIcon } from '@platform-ui/highrise'
import { Loading01Icon } from '@gohighlevel/ghl-icons/24/outline'
</script>

Loading Card Example

<template>
  <div class="card">
    <HLSpin id="card-spinner" :show="isLoading">
      <template #description> Loading card data... </template>
      <div class="card-content">
        <h3>{{ title }}</h3>
        <p>{{ description }}</p>
        <div class="actions">
          <button @click="refreshData">Refresh</button>
        </div>
      </div>
    </HLSpin>
  </div>
</template>

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

const isLoading = ref(true)
const title = ref('Card Title')
const description = ref('Card Description')

const refreshData = () => {
  isLoading.value = true
  setTimeout(() => {
    isLoading.value = false
  }, 1500)
}
</script>

Loading Table Example

<template>
  <HLSpin id="table-spinner" :show="isLoading">
    <template #description> Fetching table data... </template>
    <table>
      <thead>
        <tr>
          <th>Name</th>
          <th>Age</th>
          <th>Location</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="item in tableData" :key="item.id">
          <td>{{ item.name }}</td>
          <td>{{ item.age }}</td>
          <td>{{ item.location }}</td>
        </tr>
      </tbody>
    </table>
  </HLSpin>
</template>

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

const isLoading = ref(true)
const tableData = ref([])
</script>

Breaking Changes

1. Required ID Prop:

   • The id prop is now required for accessibility
   • Must be unique within the page context

2. Size Values:

   • Changed from 'small', 'medium', 'large' to 'sm', 'md', 'lg'
   • Default size is now 'md' instead of 'medium'

3. New Slots:

   • Added description slot for loading text
   • Added icon slot for custom loading indicator

4. Styling Changes:

   • New CSS variable system
   • Different animation implementation
   • Modified overlay styling

Best Practices

1. Accessibility:

   • Use meaningful id values
   • Provide descriptive loading messages
   • Consider screen reader users

2. Performance:

   • Use appropriate size values
   • Consider loading state timing
   • Optimize content rendering

3. User Experience:

   • Show meaningful loading descriptions
   • Use consistent spinner sizes
   • Consider loading timeouts

4. Styling:

   • Follow design system guidelines
   • Maintain consistent spacing
   • Consider dark mode

Common Patterns

Form Submission Loading

<template>
  <form @submit.prevent="handleSubmit">
    <HLSpin id="form-spinner" :show="isSubmitting">
      <template #description> Saving your changes... </template>
      <div class="form-content">
        <!-- Form fields -->
      </div>
    </HLSpin>
  </form>
</template>

Lazy Loading Component

<template>
  <HLSpin id="lazy-spinner" :show="!componentLoaded">
    <template #description> Loading component... </template>
    <component :is="lazyComponent" v-if="componentLoaded" />
  </HLSpin>
</template>

API Request Loading

<template>
  <HLSpin id="api-spinner" :show="isLoading" size="lg">
    <template #description>
      {{ loadingMessage }}
    </template>
    <div class="data-container">
      <!-- API data display -->
    </div>
  </HLSpin>
</template>