Migrating from ghl-ui CheckboxGroup to HighRise CheckboxGroup

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

Component Implementation Changes

Import Changes

- import { UICheckboxGroup, UICheckbox } from '@gohighlevel/ghl-ui'
+ import { HLCheckboxGroup, HLCheckbox } from '@platform-ui/highrise'

Basic Usage Changes

- <UICheckboxGroup
-   v-model:value="selectedValues"
- >
-   <UICheckbox value="1">Option 1</UICheckbox>
-   <UICheckbox value="2">Option 2</UICheckbox>
-   <UICheckbox value="3">Option 3</UICheckbox>
- </UICheckboxGroup>

+ <HLCheckboxGroup
+   id="preferences-group"
+   v-model:value="selectedValues"
+ >
+   <HLCheckbox value="1">Option 1</HLCheckbox>
+   <HLCheckbox value="2">Option 2</HLCheckbox>
+   <HLCheckbox value="3">Option 3</HLCheckbox>
+ </HLCheckboxGroup>

Form Integration Changes

- <UIForm :model="formModel">
-   <UIFormItem label="Preferences">
-     <UICheckboxGroup
-       v-model:value="formModel.preferences"
-     >
-       <UICheckbox value="email">Email notifications</UICheckbox>
-       <UICheckbox value="sms">SMS notifications</UICheckbox>
-       <UICheckbox value="push">Push notifications</UICheckbox>
-     </UICheckboxGroup>
-   </UIFormItem>
- </UIForm>

+ <HLForm :model="formModel" :rules="rules">
+   <HLFormItem
+     label="Preferences"
+     path="preferences"
+     required
+   >
+     <HLCheckboxGroup
+       id="preferences-group"
+       v-model:value="formModel.preferences"
+     >
+       <HLCheckbox value="email">Email notifications</HLCheckbox>
+       <HLCheckbox value="sms">SMS notifications</HLCheckbox>
+       <HLCheckbox value="push">Push notifications</HLCheckbox>
+     </HLCheckboxGroup>
+   </HLFormItem>
+ </HLForm>

Props Changes

ghl-ui Prop	HighRise Prop	Notes
v-model	v-model:value	Changed to use value prop
size	size	New size options: 'sm', 'md', 'lg'

Examples

Basic CheckboxGroup

<template>
  <HLCheckboxGroup id="basic-group" v-model:value="selectedValues">
    <HLCheckbox value="1">Option 1</HLCheckbox>
    <HLCheckbox value="2">Option 2</HLCheckbox>
    <HLCheckbox value="3">Option 3</HLCheckbox>
  </HLCheckboxGroup>
</template>

<script setup>
import { ref } from 'vue'
import { HLCheckboxGroup, HLCheckbox } from '@platform-ui/highrise'

const selectedValues = ref([])
</script>

CheckboxGroup with Validation

<template>
  <HLForm :model="formModel" :rules="rules">
    <HLFormItem label="Preferences" path="preferences" required>
      <HLCheckboxGroup
        id="preferences-group"
        v-model:value="formModel.preferences"
        :status="validationStatus"
        :validation-message="validationMessage"
      >
        <HLCheckbox value="email">Email notifications</HLCheckbox>
        <HLCheckbox value="sms">SMS notifications</HLCheckbox>
        <HLCheckbox value="push">Push notifications</HLCheckbox>
      </HLCheckboxGroup>
    </HLFormItem>
  </HLForm>
</template>

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

const formModel = ref({
  preferences: [],
})

const validationStatus = computed(() => {
  if (formModel.value.preferences.length === 0) return 'error'
  return undefined
})

const validationMessage = computed(() => {
  if (formModel.value.preferences.length === 0) return 'Please select at least one preference'
  return undefined
})

const rules = {
  preferences: [
    {
      required: true,
      message: 'Please select at least one preference',
      trigger: 'change',
    },
  ],
}
</script>

CheckboxGroup with Custom Layout

<template>
  <HLForm :model="formModel">
    <HLFormItem label="Categories" path="categories">
      <div class="grid grid-cols-2 gap-4">
        <HLCheckboxGroup id="categories-group" v-model:value="formModel.categories">
          <HLCheckbox value="tech">Technology</HLCheckbox>
          <HLCheckbox value="business">Business</HLCheckbox>
          <HLCheckbox value="science">Science</HLCheckbox>
          <HLCheckbox value="arts">Arts</HLCheckbox>
        </HLCheckboxGroup>
      </div>
    </HLFormItem>
  </HLForm>
</template>

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

const formModel = ref({
  categories: [],
})
</script>

CheckboxGroup with Disabled Options

<template>
  <HLForm :model="formModel">
    <HLFormItem label="Features" path="features">
      <HLCheckboxGroup id="features-group" v-model:value="formModel.features">
        <HLCheckbox value="basic">Basic Features</HLCheckbox>
        <HLCheckbox value="premium" disabled>Premium Features</HLCheckbox>
        <HLCheckbox value="enterprise" disabled>Enterprise Features</HLCheckbox>
      </HLCheckboxGroup>
    </HLFormItem>
  </HLForm>
</template>

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

const formModel = ref({
  features: [],
})
</script>

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
9. Group related options logically
10. Use consistent spacing and alignment
11. Implement proper error handling
12. Consider using tooltips for additional information
13. Handle disabled states properly
14. Use appropriate layout for different screen sizes

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