Migrating from ghl-ui Checkbox to HighRise Checkbox

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

Component Implementation Changes

Import Changes

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

Basic Usage Changes

- <UICheckbox
-   v-model:checked="checked"
-   label="Accept terms"
- />

+ <HLCheckbox
+   id="terms-checkbox"
+   v-model:checked="checked"
+   label="Accept terms"
+ />

Form Integration Changes

- <UIForm :model="formModel">
-   <UIFormItem label="Preferences">
-     <UICheckbox
-       v-model:checked="formModel.acceptTerms"
-       label="Accept terms and conditions"
-     />
-   </UIFormItem>
- </UIForm>

+ <HLForm :model="formModel" :rules="rules">
+   <HLFormItem
+     label="Preferences"
+     path="acceptTerms"
+     required
+   >
+     <HLCheckbox
+       id="terms-checkbox"
+       v-model:checked="formModel.acceptTerms"
+       label="Accept terms and conditions"
+     />
+   </HLFormItem>
+ </HLForm>

Props Changes

ghl-ui Prop	HighRise Prop	Notes
size	size	'lg' | 'md' | 'sm' | 'xs' | '2xs' | '3xs' Extended size options

Examples

Basic Checkbox

<template>
  <HLCheckbox id="basic-checkbox" v-model:checked="checked" label="Accept terms and conditions" />
</template>

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

const checked = ref(false)
</script>

Checkbox with Validation

<template>
  <HLForm :model="formModel" :rules="rules">
    <HLFormItem label="Terms" path="acceptTerms" required>
      <HLCheckbox
        id="terms-checkbox"
        v-model:checked="formModel.acceptTerms"
        label="Accept terms and conditions"
        :status="validationStatus"
        :validation-message="validationMessage"
      />
    </HLFormItem>
  </HLForm>
</template>

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

const formModel = ref({
  acceptTerms: false,
})

const validationStatus = computed(() => {
  if (!formModel.value.acceptTerms) return 'error'
  return undefined
})

const validationMessage = computed(() => {
  if (!formModel.value.acceptTerms) return 'You must accept the terms'
  return undefined
})

const rules = {
  acceptTerms: [
    {
      required: true,
      message: 'You must accept the terms',
      trigger: 'change',
    },
  ],
}
</script>

Indeterminate Checkbox

<template>
  <div class="space-y-4">
    <HLCheckbox
      id="parent-checkbox"
      v-model:checked="parentChecked"
      v-model:indeterminate="indeterminate"
      label="Select all"
      @change="handleParentChange"
    />

    <div class="ml-6 space-y-2">
      <HLCheckbox
        v-for="option in options"
        :key="option.value"
        :id="`child-${option.value}`"
        v-model:checked="option.checked"
        :label="option.label"
        @change="handleChildChange"
      />
    </div>
  </div>
</template>

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

const parentChecked = ref(false)
const indeterminate = ref(false)

const options = ref([
  { label: 'Option 1', value: '1', checked: false },
  { label: 'Option 2', value: '2', checked: false },
  { label: 'Option 3', value: '3', checked: false },
])

const handleParentChange = checked => {
  options.value.forEach(option => {
    option.checked = checked
  })
  indeterminate.value = false
}

const handleChildChange = () => {
  const checkedCount = options.value.filter(option => option.checked).length
  parentChecked.value = checkedCount === options.value.length
  indeterminate.value = checkedCount > 0 && checkedCount < options.value.length
}
</script>

Best Practices

1. Always provide a unique id for accessibility
2. Use v-model:checked 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 checkboxes logically
10. Use indeterminate state for parent-child relationships
11. Implement proper error handling
12. Consider using tooltips for additional information
13. Handle disabled states properly
14. Use consistent spacing and alignment

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