Migrating from ghl-ui Tag to HighRise Tag

This guide will help you migrate from the ghl-ui Tag component to the new HighRise Tag component. The Tag component has been completely redesigned with enhanced accessibility, consistent sizing, improved customization options, and better integration with the HighRise design system.

Component Implementation Changes

Import Changes

- import { UITag } from '@gohighlevel/ghl-ui'
+ import { HLTag } from '@platform-ui/highrise'

Basic Usage Changes

Basic Tag

- <UITag>Basic Tag</UITag>
+ <HLTag id="basic-tag" size="sm" color="gray">
+   Basic Tag
+ </HLTag>

Type/Color Variants

- <UITag type="success">Success</UITag>
- <UITag type="warning">Warning</UITag>
- <UITag type="error">Error</UITag>
- <UITag type="info">Info</UITag>

+ <HLTag id="success-tag" color="green">Success</HLTag>
+ <HLTag id="warning-tag" color="orange">Warning</HLTag>
+ <HLTag id="error-tag" color="red">Error</HLTag>
+ <HLTag id="info-tag" color="blue">Info</HLTag>

With Icon

- <UITag type="success">
-   <template #icon>
-     <CheckIcon class="w-4 h-4" />
-   </template>
-   Success
- </UITag>

+ <HLTag id="icon-tag" color="green" size="sm">
+   <template #icon>
+     <CheckIcon />
+   </template>
+   Success
+ </HLTag>

With Group (Migration Path)

- <UITag type="info">
-   <template #group>Status</template>
-   Active
- </UITag>

+ <!-- Replace with combination of tags or custom styling -->
+ <div class="flex items-center">
+   <HLTag id="group-label" color="gray" size="sm" :interactive="false">Status</HLTag>
+   <HLTag id="group-value" color="blue" size="sm">Active</HLTag>
+ </div>

Props Changes

Required Props

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

Modified Props

ghl-ui Prop	HighRise Prop	Notes
type	color	Changed to use semantic color system
size	size	New size system ('xs', 'sm', 'md', 'lg')
groupPosition	-	Removed, use separate tags or custom styling

New Props

Prop	Type	Default	Description
checkbox	boolean	false	Enable checkbox mode
checked	boolean	false	Control checkbox state
count	number	undefined	Display count badge
interactive	boolean	true	Enable hover/click states
dropdown	'open' | 'close' | false	false	Show dropdown indicator
disabled	boolean	false	Disable tag interactions
avatarProps	HLAvatarProps	undefined	Props for avatar slot

Color Mapping

ghl-ui Type	HighRise Color
'default'	'gray'
'primary'	'blue'
'success'	'green'
'warning'	'orange'
'error'	'red'
'info'	'blue'

Size Mapping

ghl-ui Size	HighRise Size	Notes
'small'	'sm'	Standard small size
'medium'	'md'	Standard medium size
'large'	'lg'	Standard large size
-	'xs'	New: Extra small size

Events Changes

ghl-ui Event	HighRise Event	Notes
close	close	Now includes tag ID in payload
click	-	Removed, use checked event for interaction
-	checked	New: Emitted when tag is checked/unchecked

Slots Changes

ghl-ui Slot	HighRise Slot	Notes
default	default	Main content (unchanged)
icon	icon	Icon content (unchanged)
group	-	Removed, use separate tags
-	avatar	New: Avatar content

Examples

Basic Tag with Different Colors

<template>
  <div class="flex gap-2">
    <HLTag id="gray-tag" color="gray" size="sm">Default</HLTag>
    <HLTag id="blue-tag" color="blue" size="sm">Primary</HLTag>
    <HLTag id="green-tag" color="green" size="sm">Success</HLTag>
    <HLTag id="red-tag" color="red" size="sm">Error</HLTag>
    <HLTag id="orange-tag" color="orange" size="sm">Warning</HLTag>
  </div>
</template>

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

Interactive Tag with Checkbox

<template>
  <HLTag id="checkbox-tag" color="blue" size="md" checkbox v-model:checked="isChecked" @checked="handleChecked"> Selectable Tag </HLTag>
</template>

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

const isChecked = ref(false)
const handleChecked = checked => {
  console.log('Tag checked:', checked)
}
</script>

Closable Tag with Icon

<template>
  <HLTag id="closable-tag" color="green" size="md" closable @close="handleClose">
    <template #icon>
      <CheckIcon />
    </template>
    Closable Tag
  </HLTag>
</template>

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

const handleClose = () => {
  console.log('Tag closed')
}
</script>

Tag with Count and Avatar

<template>
  <HLTag id="avatar-tag" color="indigo" size="md" :count="5">
    <template #avatar>
      <HLAvatar id="tag-avatar" name="John Doe" size="sm" />
    </template>
    User Tag
  </HLTag>
</template>

<script setup>
import { HLTag, HLAvatar } from '@platform-ui/highrise'
</script>

Breaking Changes

1. Required ID

   • New required id prop for accessibility
   • Must be unique within the page

2. Color System

   • Replaced type with color prop
   • New semantic color options
   • More consistent color palette

3. Size System

   • New size options ('xs', 'sm', 'md', 'lg')
   • More consistent sizing across components
   • Added extra small size option

4. Group Feature

   • Removed group slot and positioning
   • Use separate tags or custom styling instead

5. Event Changes

   • Removed generic click event
   • Added checked event for interaction
   • Modified close event payload

6. Interaction Model

   • New checkbox mode for selection
   • Added dropdown feature
   • Explicit interactive state control

7. Styling System

   • Uses CSS variables
   • New theming approach
   • Consistent with HighRise design system

Best Practices

1. Always provide unique id props
2. Use semantic colors appropriately
3. Choose appropriate sizes for context
4. Handle events properly
5. Consider mobile touch targets
6. Keep content concise
7. Use proper spacing
8. Follow accessibility guidelines
9. Maintain consistent styling
10. Document component usage