Morpheme

Appearance

Checkbox ​

The VCheckbox is a form input component that allows the user to select a value from a list of options. It can be used in a basic form, as a disabled input, or as part of a multi-select form with validation.

Usage ​

Basic Usage ​

To use the VCheckbox component, you will first need to import the ref function from vue. Then, create a checked variable using the ref function. Then, in your template, use the VCheckbox component with the v-model directive to bind the checked variable to the checkbox input.

INFO

The VCheckbox component is registered globally when you install with @morpheme/ui. So you don't need to import it manually.

Disabled ​

To disable the component, set the disabled prop to true.

Multiple ​

To use the VCheckbox as part of a multi-select form, you will first need to import the object and array functions from yup and the useForm hook from vee-validate. Then, create a validation schema using the object and array functions. Then, in your template, use the VCheckbox component with the name prop to bind the input to the genre field in the form values. You can also use the value and label props to specify the option value and label, respectively.

Validation ​

To use the VCheckbox component with a form validation library, you can use the name prop to bind the component to a form control. For example, with VeeValidate, you can use the useForm hook to create a form with validation schema:

Validation Mode ​

There are 2 modes. The first is eager mode, and the second is aggressive mode. The eager mode validates input when the blur event occurs. Meanwhile, aggressive mode validates the input every time the input itself changes. This can be useful when you are validating for example the minimum or maximum limits of an input.

You can change the default value for this validation mode by adding an attribute or property named validation-mode to this component.

Props ​

NameTypeDefault
modelValueBooleanfalse
labelString''
labelClassString''
inputClassString''
colorString as PropType<Colors>'primary'
sizeString''
validationModeString''
valueString''
nameString''
idString''
rulesString''
wrapperClassString''
checkedValueString''
uncheckedValueString''
disabledString''
disabledClassString''
errorClassString''
hintString''
hideErrorBooleanfalse

Events ​

update:modelValue ​

Type:

ts
(event: 'update:modelValue', value: boolean): void
(event: 'update:modelValue', value: boolean): void

Example:

vue
<script setup lang="ts">
import {ref} from 'vue';

const checked = ref(false);

const onChange = (val: boolean) => {
  console.log(val);
};
</script>

<template>
  <VCheckbox v-model="checked" @update:modelValue="onChange" />
</template>
<script setup lang="ts">
import {ref} from 'vue';

const checked = ref(false);

const onChange = (val: boolean) => {
  console.log(val);
};
</script>

<template>
  <VCheckbox v-model="checked" @update:modelValue="onChange" />
</template>

Slots ​

None

CSS Variables ​

css
:root {
  --v-checkbox-bg-color: var(--color-white);
  --v-checkbox-border-width: 1px;
  --v-checkbox-border-style: solid;
  --v-checkbox-border-color: var(--color-gray-300);
  --v-checkbox-border-radius: var(--border-radius-md);
  --v-checkbox-bg-image: url("data:image/svg+xml,%3csvg viewBox='0 0 16 16' fill='%230984DD' xmlns='http://www.w3.org/2000/svg'%3e%3cpath d='M12.207 4.793a1 1 0 010 1.414l-5 5a1 1 0 01-1.414 0l-2-2a1 1 0 011.414-1.414L6.5 9.086l4.293-4.293a1 1 0 011.414 0z'/%3e%3c/svg%3e") !important;

  // checked
  --v-checkbox-checked-bg-color: var(--color-primary-50);
  --v-checkbox-checked-border-color: var(--color-primary-600);

  // disabled
  --v-checkbox-disabled-bg-color: var(--color-gray-100);
  --v-checkbox-disabled-border-color: var(--color-gray-200);

  /* label */
  --v-checkbox-label-font-size: var(
    --input-label-font-size,
    var(--size-font-sm)
  );
  --v-checkbox-label-font-weight: var(--font-weight-medium);
  --v-checkbox-label-display: var(--v-input-label-display, block);
  --v-checkbox-label-margin-top: 1px;
  --v-checkbox-label-color: var(--color-gray-700);

  // hint
  --v-checkbox-hint-font-size: var(--v-input-hint-font-size, 14px);
  --v-checkbox-hint-color: var(--v-input-hint-color, var(--color-gray-500));
  --v-checkbox-hint-margin-top: var(--v-input-hint-margin-top, 4px);
}
:root {
  --v-checkbox-bg-color: var(--color-white);
  --v-checkbox-border-width: 1px;
  --v-checkbox-border-style: solid;
  --v-checkbox-border-color: var(--color-gray-300);
  --v-checkbox-border-radius: var(--border-radius-md);
  --v-checkbox-bg-image: url("data:image/svg+xml,%3csvg viewBox='0 0 16 16' fill='%230984DD' xmlns='http://www.w3.org/2000/svg'%3e%3cpath d='M12.207 4.793a1 1 0 010 1.414l-5 5a1 1 0 01-1.414 0l-2-2a1 1 0 011.414-1.414L6.5 9.086l4.293-4.293a1 1 0 011.414 0z'/%3e%3c/svg%3e") !important;

  // checked
  --v-checkbox-checked-bg-color: var(--color-primary-50);
  --v-checkbox-checked-border-color: var(--color-primary-600);

  // disabled
  --v-checkbox-disabled-bg-color: var(--color-gray-100);
  --v-checkbox-disabled-border-color: var(--color-gray-200);

  /* label */
  --v-checkbox-label-font-size: var(
    --input-label-font-size,
    var(--size-font-sm)
  );
  --v-checkbox-label-font-weight: var(--font-weight-medium);
  --v-checkbox-label-display: var(--v-input-label-display, block);
  --v-checkbox-label-margin-top: 1px;
  --v-checkbox-label-color: var(--color-gray-700);

  // hint
  --v-checkbox-hint-font-size: var(--v-input-hint-font-size, 14px);
  --v-checkbox-hint-color: var(--v-input-hint-color, var(--color-gray-500));
  --v-checkbox-hint-margin-top: var(--v-input-hint-margin-top, 4px);
}

Standalone Installation ​

You can also install the Checkbox component individually via @morpheme/forms package:

bash
npm i @morpheme/forms
npm i @morpheme/forms
vue
<script setup lang="ts">
import {VCheckbox} from '@morpheme/forms';

import {ref} from 'vue';

const checked = ref(false);
</script>

<template>
  <VCheckbox v-model="checked" />
</template>
<script setup lang="ts">
import {VCheckbox} from '@morpheme/forms';

import {ref} from 'vue';

const checked = ref(false);
</script>

<template>
  <VCheckbox v-model="checked" />
</template>

Storybook ​

View Storybook documentation here.