Migrating from UIDropdown to HighRise Dropdown

Migrating from ghl-ui Dropdown to HighRise Dropdown

This guide will help you migrate from the ghl-ui Dropdown component to the new HighRise Dropdown component.

Component Implementation Changes

Import Changes

- import { UIDropdown } from '@gohighlevel/ghl-ui'
+ import { HLDropdown } from '@platform-ui/highrise'

Basic Usage Changes

- <UIDropdown :options="options">
-   <UIButton>Click me</UIButton>
- </UIDropdown>

+ <HLDropdown
+   id="my-dropdown"
+   :options="options"
+   trigger="click"
+   placement="bottom-start"
+   :show-search="false"
+ >
+   <HLButton>Click me</HLButton>
+ </HLDropdown>

INFO

show-search should be set to false by default.

Props Changes

Required Changes

ghl-ui Prop	HighRise Prop	Notes
-	id	New required prop for accessibility
options	options	Enhanced options format with new features
trigger	trigger	Values: 'click', 'hover', 'focus' (default: 'click')
placement	placement	More placement options available
-	showArrow	New prop to control arrow visibility
-	width	New prop to control dropdown width (default: 182px)
-	showSelectedMark	New prop to show checkmark for selected items
-	treeMode	New prop for hierarchical navigation
-	showSearch	New prop to enable search functionality , set to false by default

Options Format

The HighRise Dropdown supports an enhanced options format with additional features:

interface HLDropdownOption {
  key: string | number
  label: string
  type?: 'default' | 'divider' | 'header' | 'search' | 'avatar' | 'icon' | 'render' | 'link'
  children?: HLDropdownOption[]
  selected?: boolean
  href?: string
  target?: string
  description?: string
  descriptionIcon?: string
  infoText?: string
  prefix?: boolean
  prefixHandler?: () => void
  titleRightSlot?: () => VNode
  searchPlaceholder?: string
  onChange?: (value: string) => void
}

Examples

Basic Dropdown

<template>
  <HLDropdown
    id="basic-dropdown"
    :show-search="false"
    :options="[
      { key: '1', label: 'Option 1' },
      { key: '2', label: 'Option 2' },
      { key: '3', label: 'Option 3' },
    ]"
  >
    <HLButton>Open Menu</HLButton>
  </HLDropdown>
</template>

Dropdown with custom options

INFO

• In GHL-UI, the render-option prop is used for custom rendering of the dropdown options.
• In HighRise, the option needs to be customized using the render type in the options array and passing a h() function to render the option.
• renderLabel is currently not supported in HighRise.

- <UIDropdown
-   :options="contextMenuItems"
-   :id="'folderMenu'"
-   placement="bottom"
-   @select="onChangeOption"
-   :render-option="(option:any) => selectOptionsComponent(option)"
- >
-   <UIButton>
-     Click to open dropdown
-   </UIButton>
- </UIDropdown>

+ <HLDropdown
+   id="folderMenu"
+   :options="contextMenuItems"
+   placement="bottom"
+   @select="onChangeOption"
+   :options="[
+     ...contextMenuItems,
+     { key: '4', label: 'Option 4', type: 'render', render: () => h('div', 'Option 4') },
+   ]"
+ >
+   <HLButton>
+     Click to open dropdown
+   </HLButton>
+ </HLDropdown>

With Search and Selected Items

<template>
  <HLDropdown id="searchable-dropdown" :options="options" show-selected-mark :width="250" :show-search="false">
    <HLButton>Select Items</HLButton>
  </HLDropdown>
</template>

<script setup>
const options = [
  { key: '1', label: 'Option 1', selected: true },
  { key: '2', label: 'Option 2' },
  {
    key: '3',
    label: 'Option 3',
    description: 'Additional information',
    descriptionIcon: 'InfoIcon',
  },
]
</script>

Tree Mode

<template>
  <HLDropdown id="tree-dropdown" :options="treeOptions" tree-mode :show-search="false">
    <HLButton>Navigate</HLButton>
  </HLDropdown>
</template>

<script setup>
const treeOptions = [
  {
    key: '1',
    label: 'Category 1',
    children: [
      { key: '1-1', label: 'Subcategory 1.1' },
      { key: '1-2', label: 'Subcategory 1.2' },
    ],
  },
  {
    key: '2',
    label: 'Category 2',
    children: [
      { key: '2-1', label: 'Subcategory 2.1' },
      { key: '2-2', label: 'Subcategory 2.2' },
    ],
  },
]
</script>

Best Practices

1. Always provide a unique id prop for accessibility
2. Use appropriate trigger based on user interaction needs
3. Consider using treeMode for complex hierarchical data
4. Enable search for dropdowns with many options
5. Use descriptions and icons to provide additional context
6. Keep option labels concise and clear
7. Use appropriate placement based on available space
8. Consider mobile responsiveness when setting width
9. Implement proper event handling
10. Follow accessibility guidelines

Additional Notes

1. Built-in search functionality with customizable placeholder
2. Support for hierarchical navigation with back button
3. Enhanced styling with hover and active states
4. Automatic overflow handling
5. Support for custom option rendering
6. Integration with other HighRise components
7. RTL layout support
8. Consistent styling through CSS variables
9. Improved accessibility features
10. Support for various content types (text, icons, avatars)