Migrating from ghl-ui Empty to HighRise Empty

This guide will help you migrate from the ghl-ui Empty component to the new HighRise Empty component. The Empty component has been enhanced with better accessibility, consistent sizing, improved customization options, and a more structured approach to empty states.

Component Implementation Changes

Import Changes

- import { UIEmpty } from '@gohighlevel/ghl-ui'
+ import { HLEmpty } from '@platform-ui/highrise'

Basic Usage Changes

Basic Empty State

- <UIEmpty
-   id="no-data"
-   title="No data found"
-   description="There are no items to display at this time."
-   :icon="SearchLgIcon"
- />

+ <HLEmpty
+   id="no-data"
+   title="No data found"
+   description="There are no items to display at this time."
+   size="lg"
+   icon="default"
+ />

With Action Buttons

- <UIEmpty
-   id="no-projects"
-   title="No projects found"
-   description="You haven't created any projects yet."
-   positiveText="Create Project"
-   @positiveClick="createProject"
- />

+ <HLEmpty
+   id="no-projects"
+   title="No projects found"
+   description="You haven't created any projects yet."
+   size="lg"
+   positive-text="Create Project"
+   negative-text="Learn More"
+   :positive-icon="PlusIcon"
+   @positive-click="createProject"
+   @negative-click="learnMore"
+ />

With Custom Icon

- <UIEmpty
-   id="custom-icon"
-   title="No files found"
-   :icon="PhoneCall01Icon"
- />

+ <HLEmpty
+   id="custom-icon"
+   title="No files found"
+   description="Upload files to get started"
+   :custom-icon="Building01Icon"
+   custom-icon-color="var(--indigo-600)"
+   custom-icon-bg-color="var(--indigo-100)"
+ />

With Custom Media Content

- <UIEmpty id="custom-media">
-   <template #media>
-     <img
-       src="/path/to/empty-inbox.svg"
-       alt="Empty inbox illustration"
-       class="w-32 h-32 mb-4"
-     />
-   </template>
- </UIEmpty>

+ <HLEmpty id="custom-media">
+   <template #header>
+     <div class="flex items-center gap-2">
+       <div class="flex items-center justify-center w-10 h-10 rounded-full bg-gray-100">
+         <Building02Icon class="w-4 h-4 text-gray-600" />
+       </div>
+       <p class="text-xl font-medium">Custom Header</p>
+     </div>
+   </template>
+ </HLEmpty>

Props Changes

Required Props

ghl-ui Prop	HighRise Prop	Notes
id	id	Required for accessibility (unchanged)

Modified Props

ghl-ui Prop	HighRise Prop	Notes
title	title	Title text (unchanged)
description	description	Description text (unchanged)
positiveText	positiveText	Primary action button text (unchanged)
negativeText	negativeText	Secondary action button text (unchanged)
icon	icon	Now accepts predefined types instead of component
-	size	New: Controls component size ('lg', 'md', 'sm')
-	positiveIcon	New: Icon component for positive button
-	customIcon	New: Custom icon component
-	customIconColor	New: Color for custom icon
-	customIconBgColor	New: Background color for custom icon

Removed Props

• Custom icon component passed directly (use customIcon instead)
• Custom styling props (use design system tokens)

Icon Types

The icon prop now accepts these predefined values:

• 'default'
• 'info'
• 'success'
• 'loader'
• 'error'
• 'warning'

Event Changes

ghl-ui Event	HighRise Event	Notes
positiveClick	positiveClick	Unchanged: Emitted when positive button clicked
negativeClick	negativeClick	Unchanged: Emitted when negative button clicked

Slot Changes

ghl-ui Slot	HighRise Slot	Notes
media	header	Renamed: For custom header content/illustrations
actions	-	Removed: Use positiveText/negativeText props instead
default	-	Removed: Use description prop for content

Examples

Basic Empty State with Icon

<template>
  <HLEmpty
    id="basic-empty"
    title="No Results Found"
    description="Try adjusting your search or filters to find what you're looking for."
    size="lg"
    icon="info"
  />
</template>

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

With Action Buttons and Icon

<template>
  <HLEmpty
    id="action-empty"
    title="No Projects"
    description="Get started by creating your first project"
    size="md"
    positive-text="Create Project"
    negative-text="Learn More"
    :positive-icon="PlusIcon"
    icon="default"
    @positive-click="handleCreate"
    @negative-click="handleLearnMore"
  />
</template>

<script setup>
import { HLEmpty } from '@platform-ui/highrise'
import { PlusIcon } from '@gohighlevel/ghl-icons/24/outline'

const handleCreate = () => {
  // Handle create action
}

const handleLearnMore = () => {
  // Handle learn more action
}
</script>

With Custom Icon and Colors

<template>
  <HLEmpty
    id="custom-icon-empty"
    title="No Files"
    description="Upload files to get started"
    size="lg"
    :custom-icon="Building01Icon"
    custom-icon-color="var(--indigo-600)"
    custom-icon-bg-color="var(--indigo-100)"
    positive-text="Upload Files"
    @positive-click="handleUpload"
  />
</template>

<script setup>
import { HLEmpty } from '@platform-ui/highrise'
import { Building01Icon } from '@gohighlevel/ghl-icons/24/outline'

const handleUpload = () => {
  // Handle file upload
}
</script>

With Custom Header

<template>
  <HLEmpty id="custom-header-empty" title="No Messages" description="Your inbox is empty" size="lg">
    <template #header>
      <div class="flex items-center gap-2">
        <div class="flex items-center justify-center w-10 h-10 rounded-full bg-gray-100">
          <Building02Icon class="w-4 h-4 text-gray-600" />
        </div>
        <p class="text-xl font-medium">Custom Empty State</p>
      </div>
    </template>
  </HLEmpty>
</template>

<script setup>
import { HLEmpty } from '@platform-ui/highrise'
import { Building02Icon } from '@gohighlevel/ghl-icons/24/outline'
</script>

Size Mapping

ghl-ui Size	HighRise Size	Notes
Default	lg	Large size - for main content areas
-	md	Medium size - for sections and panels
-	sm	Small size - for compact spaces

Breaking Changes

1. Icon System Changes

   • Removed direct icon component prop
   • Added predefined icon types
   • New custom icon system with color control

2. Slot Changes

   • Renamed media slot to header
   • Removed actions slot in favor of props
   • Removed default slot

3. Size System

   • Added explicit size control
   • Fixed dimensions for each size
   • Standardized spacing

4. Action Buttons

   • More structured approach to actions
   • Added support for button icons
   • Consistent button styling

5. Styling System

   • Uses design system tokens
   • Removed custom styling props
   • Standardized color system

6. Content Structure

   • More structured content layout
   • Consistent spacing
   • Better responsive behavior

Best Practices

1. Always provide unique id props
2. Use appropriate size for context
3. Choose semantic icon types
4. Keep descriptions concise
5. Use action buttons purposefully
6. Follow color system guidelines
7. Maintain responsive design
8. Consider mobile viewports
9. Follow accessibility guidelines
10. Document component usage

TypeScript Support

The component includes comprehensive TypeScript support:

type IconTypes = 'default' | 'info' | 'success' | 'loader' | 'error' | 'warning'

type HLEmptySize = 'lg' | 'md' | 'sm'

interface HLEmptyProps {
  id: string
  size: HLEmptySize
  title: string
  description: string
  positiveIcon?: () => VNodeChild
  positiveText: string
  negativeText: string
  icon: IconTypes
  customIcon?: () => VNodeChild
  customIconColor?: string
  customIconBgColor?: string
}