Migrating from ghl-ui Alert to HighRise Alert

This guide provides a comprehensive overview of migrating from the ghl-ui Alert component to the new HighRise Alert component.

Component Implementation Changes

Import Changes

- import { UIAlert } from '@gohighlevel/ghl-ui'
+ import { HLAlert } from '@platform-ui/highrise'

Basic Usage Changes

- <UIAlert type="info" message="This is an alert message">
-   <template #actions>
-     <UIButton text> Action 1</UIButton>
-     <UIButton text> Action 2</UIButton>
-   </template>
- </UIAlert>

+ <HLAlert
+   id="my-alert"
+   type="notification"
+   color="gray" <!-- Refer Type to Color Mapping section below -->
+   content="This is an alert message"
+   :actionOne="{
+     text: 'Action 1',
+     onActionClick: () => console.log('Action 1 clicked')
+   }"
+   :actionTwo="{
+     text: 'Action 2',
+     onActionClick: () => console.log('Action 2 clicked')
+   }"
+   width="100%"
+ />

INFO

Always set the width to 100%.

Props Changes

Core Props

ghl-ui Prop	HighRise Prop	Notes
type	color	See Type Mapping section below
closable	closable	Boolean (default: true)
-	id	Required string for accessibility
-	type	'notification' or 'alert' (default: 'notification')
-	title	Optional title text
-	content	Main alert content
-	autoClose	Boolean or number (ms) for auto-closing
-	width	Alert width (default: '540px')
-	height	Alert height (default: '48px')
-	role	ARIA role (default: 'alert')

Type to Color Mapping

The old type prop maps to the new color prop as follows:

Old Type	New Color
default	gray
info	blue
success	green
warning	orange
error	red
white	white
gray	gray

Action Configuration

The new HighRise Alert uses a structured action configuration system for both primary and secondary actions:

interface HLAlertActionItem {
  text?: string
  iconLeft?: Component
  iconRight?: Component
  link?: string
  loading?: boolean
  disabled?: boolean
  ariaLabel?: string
  onActionClick?: () => void
}

Actions are configured through the actionOne and actionTwo props:

• actionOne: Primary action (uses color based on alert color)
• actionTwo: Secondary action (uses blue color for white/gray alerts, matches alert color otherwise)

Event Changes

ghl-ui Event	HighRise Event	Notes
@close	@close	Emitted with alert id parameter
-	@actionOne	Emitted when primary action is clicked
-	@actionTwo	Emitted when secondary action is clicked

Slots Changes

ghl-ui Slot	HighRise Alternative	Notes
default	content prop or default slot	Content can be provided via prop or slot
icon	icon slot	Custom icon slot remains available
actions	Use actionOne/actionTwo props	Actions are now configured via props
title	Use title prop	Title is now configured via prop
content	Use content prop	Content is now configured via content prop

Examples

Basic Alert

- <UIAlert type="info" message="This is an alert message">
-   <template #actions>
-     <UIButton text>Action</UIButton>
-   </template>
- </UIAlert>

+ <HLAlert id="basic-alert" type="notification" content="This is a basic alert message" closable color="gray" width="100%" />

Alert with Title and Custom Icon

- <UIAlert id="custom-alert" type="success" message="Operation completed successfully">
-   <template #icon>
    <CheckCircleIcon class="w-5 h-5" />
  </template>
- </UIAlert>
+ <HLAlert id="custom-alert" type="success" content="Operation completed successfully" closable color="green" width="100%">
+ <template #icon>
+   <CheckCircleIcon class="w-5 h-5" />
+ </template>
+ </HLAlert>

Alert with Actions

- <UIAlert id="action-alert" type="info" message="New features are available">
-   <template #actions>
-     <UIButton text> View Details</UIButton>
-     <UIButton text> Learn More</UIButton>
-   </template>
- </UIAlert>

+ <HLAlert
+   id="action-alert"
+   color="blue"
+   type="notification"
+   title="Information"
+   content="New features are available"
+   :actionOne="{
+     text: 'View Details',
+     iconLeft: EyeIcon,
+     variant: 'text',
+     onActionClick: handleViewDetails,
+   }"
+   :actionTwo="{
+     text: 'Learn More',
+     iconRight: ArrowRightIcon,
+     variant: 'text',
+     link: 'https://docs.example.com',
+   }"
+   width="100%"
+ />

Auto-closing Alert

- <template>
-   <HLAlert
-     id="auto-close-alert"
-     color="orange"
-     type="notification"
-     content="This alert will close in 5 seconds"
-     :autoClose="5000"
-     @close="handleClose"
-   />
- </template>

+ <HLAlert
+   id="auto-close-alert"
+   color="orange"
+   type="notification"
+   content="This alert will close in 5 seconds"
+   :autoClose="5000"
+   @close="handleClose"
+   width="100%"
+ />

Alert without close button

- <UIAlert id="no-close-alert" type="info" message="This alert cannot be closed" :closable="false">
-   <template #actions>
-     <UIButton text> Action</UIButton>
-   </template>
- </UIAlert>

+ <HLAlert id="no-close-alert" type="info" content="This alert cannot be closed" :closable="false" color="gray" width="100%" />

Alert with custom content

Content can be provided via the content prop or default slot

- <UIAlert id="custom-content-alert" type="success" message="Operation completed successfully">
-   <template #content>
-     <p>This is a custom content message</p>
-   </template>
- </UIAlert>

+ <HLAlert id="custom-content-alert" type="success" content="Operation completed successfully" width="100%">
+   <p>This is a custom content message</p>
+ </HLAlert>

Breaking Changes

1. Required ID Prop: The id prop is now required for accessibility purposes
2. Color System: The type prop has been replaced with color and a new type prop for alert variants, ghl-ui default is mapped to gray
3. Action System: Actions are now configured through actionOne and actionTwo props instead of slots
4. Icon System: Default icons are provided based on color, with option to override via slot
5. Event System: New action events (@actionOne, @actionTwo) for better action handling
6. Content Management: Content can be provided via prop or default slot
7. Accessibility: Enhanced ARIA support with role prop and better keyboard navigation

Best Practices

1. Always provide a unique id prop for accessibility
2. Use appropriate colors to convey message type:
   • blue for info
   • green for success
   • orange for warning
   • red for error
   • white or gray for neutral messages
3. Keep content concise and clear
4. Use type="notification" for temporary messages and type="alert" for important persistent messages
5. Implement proper event handling for actions and close events
6. Use auto-close for temporary notifications
7. Add descriptive action labels and aria-labels for accessibility
8. Consider mobile responsiveness when setting width
9. Use appropriate icons that match the alert's purpose
10. Maintain consistent styling across your application

Additional Features

1. Content Ellipsis: Automatic content truncation with tooltip
2. Auto-close Timer: Pauses on hover, resumes on mouse leave
3. Link Support: Actions can be configured as links
4. Loading States: Actions support loading states
5. Accessibility: Improved ARIA attributes
6. Responsive Design: Configurable width and height
7. Theme Integration: Consistent styling with design system
8. Type Safety: Full TypeScript support
9. Icon Integration: Automatic icon selection based on color
10. Action Variants: Consistent text variant styling for actions