Migrating from ghl-ui Select to HighRise Select

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

Component Implementation Changes

Import Changes

- import { UISelect } from '@gohighlevel/ghl-ui'
+ import { HLSelect } from '@platform-ui/highrise'

Basic Usage Changes

- <UISelect
-   v-model:value="selectedValue"
-   :options="options"
-   placeholder="Select an option"
-  @update:value="handleChange"
- />

+ <HLSelect
+   v-model:value="selectedValue"
+   :options="options"
+   placeholder="Select an option"
+   @update:value="handleChange"
+ />

Form Integration Changes

- <UIForm :model="formModel">
-   <UIFormItem label="Country">
-     <UISelect
-       v-model:value="formModel.country"
-       :options="countryOptions"
-       placeholder="Select country"
-       @update:value="handleChange"
-     />
-   </UIFormItem>
- </UIForm>

+ <HLForm :model="formModel" :rules="rules">
+   <HLFormItem
+     label="Country"
+     path="country"
+     required
+   >
+     <HLSelect
+       id="country-select"
+       v-model:value="formModel.country"
+       :options="countryOptions"
+       placeholder="Select country"
+       @update:value="handleChange"
+     />
+   </HLFormItem>
+ </HLForm>

Multiple Selection Changes

- <UISelect
-   id="multi-select"
-   v-model:value="selectedValues"
-   :options="options"
-   multiple
-   maxTagCount={3}
- >
-   <template #tag="{ option }">
-     <span>{{ option.label }}</span>
-   </template>
- </UISelect>

+ <HLSelect
+   id="multi-select"
+   v-model:value="selectedValues"
+   :options="options"
+   multiple
+   maxTagCount="responsive"
+   :roundedTags="true"
+ />

Search Implementation Changes

- <UISelect
-   id="search-select"
-   v-model="selectedValue"
-   :options="options"
-   filterable
- />

+ <HLSelect
+   id="search-select"
+   v-model:value="selectedValue"
+   :options="options"
+   filterable
+   :showSearchIcon="true"
+ />

Props Changes

ghl-ui Prop	HighRise Prop	Notes
size	'lg' | 'md' | 'sm' | 'xs' | '2xs' | '3xs'	Extended size options
showSearchIcon	boolean	Shows search icon in input
options	SelectOption[]	Array of options to display. Accepts extended options via SelectOption interface
inline	boolean	Use inline styling
showInlineCTA	boolean	Show confirm/cancel buttons
showInlineBottomBorder	boolean	Show bottom border in inline mode
roundedTags	boolean	Use rounded styling for tags
showAvatarInTags	boolean	Show avatar in multiple selection
optionRenderer	(option: SelectOption) => VNodeChild | undefined	Custom function to render options
optionHeight	number | undefined	Height of each listed option in pixels
placeholder	string | undefined	Placeholder text when no selection
showArrow	boolean | undefined	Show/hide dropdown arrow
showCheckmark	boolean | undefined	Show/hide option checkmark
to	string | boolean | undefined	Teleport dropdown to specific element/disable teleport.

Examples

Basic Select

<template>
  <HLForm id="basic-select-form" :model="model" :rules="rules">
    <HLFormItem label="Country" path="country" required>
      <HLSelect v-model:value="model.country" :options="countries" placeholder="Select a country" filterable />
    </HLFormItem>
  </HLForm>
</template>

<script setup>
import { ref } from 'vue'
import { HLForm, HLFormItem, HLSelect } from '@platform-ui/highrise'

const model = ref({
  country: null,
})

const countries = [
  { label: 'United States', value: 'US' },
  { label: 'Canada', value: 'CA' },
  { label: 'United Kingdom', value: 'UK' },
  { label: 'Australia', value: 'AU' },
]

const rules = {
  country: [
    {
      required: true,
      message: 'Please select a country',
      trigger: 'change',
    },
  ],
}
</script>

Multiple Select

<template>
  <HLForm id="multiple-select-form" :model="model">
    <HLFormItem label="Skills" path="skills">
      <HLSelect v-model:value="model.skills" :options="skillOptions" multiple filterable placeholder="Select skills" />
    </HLFormItem>
  </HLForm>
</template>

<script setup>
import { ref } from 'vue'
import { HLForm, HLFormItem, HLSelect } from '@platform-ui/highrise'

const model = ref({
  skills: [],
})

const skillOptions = [
  { label: 'JavaScript', value: 'js' },
  { label: 'TypeScript', value: 'ts' },
  { label: 'Vue.js', value: 'vue' },
  { label: 'React', value: 'react' },
  { label: 'Angular', value: 'angular' },
]
</script>

Custom Rendering

The select component provides powerful customization options through renderOption and tagRenderer props. These allow you to customize both how options appear in the dropdown menu and how selected values are displayed as tags.

How Custom Rendering Works

1. Render Option (renderOption):

   • Customizes how the option appear in the dropdown menu
   • Can return plain text or complex Vue components
   • Has access to the full option object including custom properties

2. Tag Rendering (tagRenderer):

   • Customizes how selected values appear in the input
   • Used only when an option is selected
   • Particularly useful with multiple selection

3. Option Properties:

   • label: The display text or component
   • value: The underlying value
   • tagRenderer: Optional custom tag rendering
   • renderOption: Optional custom label rendering
   • description: Additional text shown below the label
   • Custom styling properties (backgroundColor, color, etc.)

4. Option Renderer:

   • Customizes how a option appear in the dropdown menu
   • Can return plain text or complex Vue components
   • It will have parameter option

Basic Option

// Basic option
{
  label: "Option 1",
  value: "opt1",
  description: "Optional description"
}

Group Option

// Group with children
{
  type: "group",
  label: "Group 1",
  key: "group1",
  children: [
    { label: "Child 1", value: "child1" },
    { type: "divider" },
    { label: "Child 2", value: "child2" }
  ]
}

Tag Renderer

// Tag Renderer
{
  label: "Option 1",
  value: "opt1",
  tagRenderer: () => h(HLTag, { color: "blue" }, "Tag Content")
}

Best Practices

1. Always provide a unique id for accessibility
2. Use v-model:value for two-way binding
3. Implement proper form validation
4. Use appropriate size variants
5. Consider mobile responsiveness
6. Add proper ARIA labels
7. Handle loading states appropriately
8. Use descriptive labels and placeholders
9. Group related options when appropriate
10. Use filterable prop for long option lists
11. Implement proper error handling
12. Consider using tooltips for additional information
13. Use clearable prop when appropriate
14. Handle disabled states properly

Additional Notes

1. The component automatically handles focus states
2. Error states are managed through validation status
3. Supports keyboard navigation
4. Maintains consistent styling with other form components
5. Handles disabled states consistently
6. Integrates seamlessly with form validation
7. Maintains accessibility standards
8. Supports custom styling through CSS variables
9. Provides clear visual feedback for all states
10. Works well on both desktop and mobile devices
11. Supports both controlled and uncontrolled modes
12. Includes built-in validation support