Migrating from ghl-ui Notification to HighRise Notification

This guide will help you migrate from the ghl-ui Notification component to the new HighRise Notification system. The notification system has been redesigned to provide better consistency and integration with the HLAlert component.

Component Implementation Changes

Import Changes

- import { useNotification } from '@gohighlevel/ghl-ui'
+ import {
+   HLAlert,
+   transformNotificationOpts,
+   useHLNotification,
+ } from "@platform-ui/highrise";

[NOTE]

useHLNotification is used to create a notification instance. Using the notification instance we create the notification using create method and pass the type as type prop to it unlike ghl-ui where we can choose to pass the type as notification.<type>(...props)

Basic Usage

- const notification = useNotification()
- notification.success({
-   title: 'Success',
-   duration: 3000
- })

+ const notification = useHLNotification()
+ const notificationInstance = notification.create({ // Use the create method to create a notification instance and pass the type
+   content: () => h(HLAlert,
+     {
+       type: 'success',
+       title: 'Success',
+       onClose: () => {
+         notificationInstance.destroy()
+        },
+       autoClose: 3000,
+       width: '365px',
+     },
+    ),
+ })

With Description

- const notification = useNotification()
- notification.success({
-   title: 'Success',
-   description: 'Operation completed successfully',
-   duration: 3000
- })

+ const notification = useHLNotification()
+ const notificationInstance = notification.create({
+   content: () => h(HLAlert,
+     {
+       title: 'Success',
+       onClose: () => {
+         notificationInstance.destroy()
+        },
+       autoClose: 3000,
+       width: '365px',
+     },
+     {
+       default: 'Operation completed successfully',
+     }
+    ),
+ })

Using transformNotificationOpts util to migrate existing notification implementation

You can use the transformNotificationOpts util to transform the old props of notification methods to the new HighRise props. This can be used as a stop-gap measure while migrating large apps and can be customized later as and when needed.

const notifRef = ref()

- const notification = useNotification()
+ const notification = useHLNotification()

onBeforeUnmount(() => notification.destroyAll())

const notifOpts = {
  title: 'Success',
  duration: 3000,
}

function openNotification() {
- notifRef.value = notification.success(notifOpts)
+ notifRef.value = notification.create(transformNotificationOpts({
+   ...notifOpts,
+   type: 'success', // notification.<type> is not supported in HighRise; pass type as props
+ }))
}

Configuration Changes

Provider Setup

[NOTE]

The notification system requires the HLContentWrap or HLNotificationProvider component as a provider. The provider must be initiated in at least a one-level-above parent component from where the notification instance is initiated.

Parent.vue

<template>
  <HLContentWrap :notification-config="notificationConfig" :namespace="nameOfYourApp">
    <Child />
  </HLContentWrap>
</template>

<script setup>
import Child from './components/Child.vue'
import { HLContentWrap } from '@platform-ui/highrise'
</script>

Child.vue

<template>
  <HLButton id="notif-trigger" @click="openNotification"></HLButton>
</template>

<script setup lang="ts">
import { useHLNotification } from '@platform-ui/highrise'
import { ref, onBeforeUnmount } from 'vue'

const notification = useHLNotification()

const openNotification = props => {
  notification.create(props)
}

onBeforeUnmount(() => notification.destrolAll())
</script>

Configuration Options

ghl-ui Config	HighRise Config	Notes
placement	placement	Values: 'top', 'top-left', 'top-right', 'bottom', 'bottom-left', 'bottom-right'
max	max	Maximum number of notifications to show
-	scrollable	Whether to allow scrolling when max is reached
-	containerClass	Custom class for notification container
-	containerStyle	Custom style for notification container
-	to	Target element to mount notifications

Notification Types

Notifications now use the Alert component with type="notification". Color mapping:

Old Type	New Color	Notes
info	blue	Information notifications
success	green	Success notifications
warning	orange	Warning notifications
error	red	Error notifications
default	gray	Default notifications

Examples

Basic Notification

import { useHLNotification, HLAlert } from '@platform-ui/highrise'
import { h } from 'vue'
const notification = useHLNotification()
function openNotification() {
  const notificationInstance = notification.create({
    content: () =>
      h(
        HLAlert,
        {
          title: 'Notification',
          closable: true,
          id: 'test-alert',
          onClose: () => {
            notificationInstance.destroy()
          },
        },
        {
          default:
            'Lorem ipsum dolor sit amet consectetur adipisicing elit Lorem ipsum dolor sit amet consectetur adipisicing elitLorem ipsum dolor sit amet consectetur adipisicing elitLorem ipsum dolor sit amet consectetur adipisicing elit',
        }
      ),
  })
}

Notification with Actions

<script setup>
import { useHLNotification } from '@platform-ui/highrise'
import { EyeIcon, ArrowRightIcon } from '@gohighlevel/ghl-icons/24/outline'

const notification = useHLNotification()

const showActionNotification = () => {
  const notificationInstance = notification.create({
    content: () =>
      h(
        HLAlert,
        {
          title: 'Notification',
          closable: true,
          id: 'test-alert',
          actionOne: {
            text: 'View Message',
            iconLeft: EyeIcon,
            onActionClick: handleViewMessage,
          },
          actionTwo: {
            text: 'Go to Inbox',
            iconRight: ArrowRightIcon,
            link: '/inbox',
          },
        },
        {
          default:
            'Lorem ipsum dolor sit amet consectetur adipisicing elit Lorem ipsum dolor sit amet consectetur adipisicing elitLorem ipsum dolor sit amet consectetur adipisicing elitLorem ipsum dolor sit amet consectetur adipisicing elit',
        }
      ),
    title: 'Notification',
  })
}
</script>

Best Practices

1. Always provide a unique id prop for each notification
2. Use appropriate colors to convey message type
3. Keep notification content concise
4. Use appropriate duration based on content importance
5. Implement proper action handling
6. Consider mobile responsiveness
7. Follow accessibility guidelines
8. Use consistent styling
9. Handle notification cleanup properly
10. Configure placement based on UX requirements

Breaking Changes

1. Notifications are now created using the useHLNotification composable
2. Notifications use the Alert component for rendering
3. New required id prop for accessibility
4. Changed configuration structure
5. Different type/color mapping
6. New provider requirement (HLContentWrap)
7. Changed styling variables and theme overrides
8. Notification dimensions are standardized
9. Actions are handled through Alert component props
10. Auto-close behavior is more configurable