Migrating from ghl-ui Alert to HighRise Alert

This guide covers migrating from ghl-ui UIAlert to HighRise HLAlert. HighRise adds structured actions, mapped color semantics, and improved sizing defaults.

Component Implementation Changes

Import Changes

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

Basic Usage Changes

- <UIAlert id="info" type="info" message="This is an alert message" />
+ <HLAlert id="info" color="blue" type="notification" content="This is an alert message" />

Props Changes

Core Props

| ghl-ui Prop | HighRise Prop | Notes | | --------------------- | --------------------------------------- | --------------------------------------------------- | --------------------------------- | | id | id | Required in both | | type | color | Map old type → new color (see below) | | closable | closable | Same meaning; default true | | message (prop/slot) | content prop or default slot | Both props and slot supported | | title slot | title prop | Title is now prop-only | | - | type | 'notification' | 'alert'(default'notification') | | - | autoClose | false or number (ms) | | - | width/height/maxWidth/maxHeight | Optional sizing tokens (maxWidth defaults to 540px) | | - | role | Default 'alert'; sets aria-live accordingly |

Type to Color Mapping

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

Action Configuration

Use props instead of the actions slot:

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

• actionOne: Primary action (follows alert color; gray/white stay gray)
• actionTwo: Secondary action (blue for white/gray alerts; alert color otherwise)

Event Changes

ghl-ui Event	HighRise Event	Notes
@close	@close	Emits alert id
-	@actionOne	Fires when primary action triggered
-	@actionTwo	Fires when secondary action triggered

Slots Changes

ghl-ui Slot	HighRise Alternative	Notes
default	default slot or content prop	Rich content via slot; short text via prop
icon	icon slot	Same behavior
actions	alertActions slot or actionOne/actionTwo props	Use props for standard actions; slot to override
title	title prop	Title moved to prop
content	default slot or content prop	Same content support

Examples

Basic Alert

- <UIAlert id="basic-alert" type="info" message="This is an alert message" />
+ <HLAlert id="basic-alert" color="blue" type="notification" content="This is an alert message" />

Alert with Title and Custom Icon

- <UIAlert id="custom-alert" type="success" message="Done!">
-   <template #icon><CheckCircleIcon /></template>
- </UIAlert>
+ <HLAlert id="custom-alert" color="green" type="notification" title="Done!" content="Operation completed">
+   <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',
+   }"
+ />

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>

Breaking Changes

1. Title/content now props-first — title is a prop; content can be prop or default slot (no message prop).
2. Actions via props — replace actions slot with actionOne/actionTwo props or alertActions slot.
3. Color system — use color with the mapping table; type now means 'notification' | 'alert'.
4. Defaults shifted — default color is white; type defaults to 'notification'; auto-close is opt-in.

Best Practices

1. Keep id unique for testing and accessibility hooks.
2. Map old type to color; keep type="notification" unless you need alert.
3. Prefer props for actions; override with alertActions only when layout must differ.
4. Use concise content; rely on the default slot when you need rich markup.
5. When using autoClose, always handle close to update local state.

MCPs: prefer configuring buttons through actionOne/actionTwo; keep color aligned with mapped types and avoid overriding size via inline styles unless necessary.