Checkbox Input
Basic usage
Boolean: Model value: false
Strings: Model value: []
<script setup lang="ts">
import { CheckboxInput } from '@vuetags/inputs';
import type { CheckboxModel } from '@vuetags/inputs';
import { ref } from 'vue';
const model = ref<CheckboxModel>(false);
const listModel = ref<CheckboxModel>([]);
</script>
<template>
<p>
<strong>Boolean:</strong>
<checkbox-input v-model="model" />
Model value: <span>{{ model }}</span>
</p>
<p>
<strong>Strings:</strong>
<checkbox-input v-model="listModel" value="first" />
<checkbox-input v-model="listModel" value="second" />
Model value: <span>{{ listModel }}</span>
</p>
</template><script setup>
import { CheckboxInput } from '@vuetags/inputs';
import { ref } from 'vue';
const model = ref(false);
const listModel = ref([]);
</script>
<template>
<p>
<strong>Boolean:</strong>
<checkbox-input v-model="model" />
Model value: <span>{{ model }}</span>
</p>
<p>
<strong>Strings:</strong>
<checkbox-input v-model="listModel" value="first" />
<checkbox-input v-model="listModel" value="second" />
Model value: <span>{{ listModel }}</span>
</p>
</template>Model
You can use the v-model as you're used to in Vue. Check the official documentation for more information on how to use models. You can use a boolean for a single checkbox or an Array or Set when combining multiple checkboxes. See the documentation on forms for more information.
INFO
The model in the component makes sure that there are no duplicate values in the model. You should not use multiple checkboxes using the same model that have the same value.
Props
The CheckboxInput element allows all default HTML properties and attributes. Apart from those the following properties are added:
value
The value property is used to distinguish multiple combined checkboxes. This value will be added to the model when it's selected. This can be a static string or a dynamic value.
<script setup lang="ts">
import { CheckboxInput } from '@vuetags/inputs';
import { computed } from 'vue';
const dynamicValue = computed<string>(() => 'second');
</script>
<template>
<p>
<checkbox-input value="first" />
<checkbox-input :value="dynamicValue" />
</p>
</template><script setup>
import { CheckboxInput } from '@vuetags/inputs';
import { computed } from 'vue';
const dynamicValue = computed(() => 'second');
</script>
<template>
<p>
<checkbox-input value="first" />
<checkbox-input :value="dynamicValue" />
</p>
</template>validators
Validators are used to validate the user's input. Validation is triggered manually by using the validate function. These are either a single validator or an array of multiple validators. These can be predefined presets and/or custom functions.
Type definition
// One or more validation presets and/or custom functions
validators?: Validation | Validation[];
// Combination of presets and/or functions
type Validation = ValidationPreset | ValidationFunction;
// Available validation presets
type ValidationPreset = 'required';
// Validation function. Needs to return false or a string if validation fails,
// true otherwise
export type ValidationFunction<ModelValue = string> =
(modelValue: ModelValue, ...args: unknown[]) => boolean | string;A single validator
A single validator can be directly added to the prop. This can be done directly in the template or as a variable.
<script setup lang="ts">
import { CheckboxInput } from '@vuetags/inputs';
</script>
<template>
<!-- A single preset -->
<checkbox-input validators="required" />
<!-- A single function -->
<checkbox-input :validators="(value: boolean) => value === true" />
</template><script setup>
import { CheckboxInput } from '@vuetags/inputs';
</script>
<template>
<!-- A single preset -->
<checkbox-input validators="required" />
<!-- A single function -->
<checkbox-input :validators="(value) => value === true" />
</template>Multiple validators
Multiple validators can be added as an array. This can be a combination of custom functions and/or presets.
<script setup lang="ts">
import { CheckboxInput } from '@vuetags/inputs';
const validatorFunction = (value: string[]) => value.length > 1;
</script>
<template>
<checkbox-input :validators="['required', validatorFunction]" />
</template><script setup>
import { CheckboxInput } from '@vuetags/inputs';
const validatorFunction = (value) => value.length > 1;
</script>
<template>
<checkbox-input :validators="['required', validatorFunction]" />
</template>Available presets
required
The required preset checks if the checkbox is checked. If the checkbox is not checked, it will return 'required' in the validation result.
Emits
The CheckboxInput element allows the default HTML events that are normally emitted.
Exposed functions
By utilizing Vue template refs you have access to additional functions. These can be programmatically triggered to perform the following actions.
focus
Programmatically trigger focus on the element.
<script setup lang="ts">
import { CheckboxInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef<InstanceType<typeof CheckboxInput>>('checkbox-input');
function focus(): void {
element.value.focus();
}
</script>
<template>
<checkbox-input ref="checkbox-input" />
<button @click="focus">Trigger focus on element</button>
</template><script setup>
import { CheckboxInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef('checkbox-input');
function focus() {
element.value.focus();
}
</script>
<template>
<checkbox-input ref="checkbox-input" />
<button @click="focus">Trigger focus on element</button>
</template>blur
Programmatically remove focus from the element.
<script setup lang="ts">
import { CheckboxInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef<InstanceType<typeof CheckboxInput>>('checkbox-input');
function blur(): void {
element.value.blur();
}
</script>
<template>
<checkbox-input ref="checkbox-input" />
<button @click="blur">Remove focus from element</button>
</template><script setup>
import { CheckboxInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef('checkbox-input');
function blur() {
element.value.blur();
}
</script>
<template>
<checkbox-input ref="checkbox-input" />
<button @click="blur">Remove focus from element</button>
</template>check
Programmatically check the element.
<script setup lang="ts">
import { CheckboxInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef<InstanceType<typeof CheckboxInput>>('checkbox-input');
function check(): void {
element.value.check();
}
</script>
<template>
<checkbox-input ref="checkbox-input" />
<button @click="check">Check the element</button>
</template><script setup>
import { CheckboxInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef('checkbox-input');
function check() {
element.value.check();
}
</script>
<template>
<checkbox-input ref="checkbox-input" />
<button @click="check">Check the element</button>
</template>uncheck
Programmatically uncheck the element.
<script setup lang="ts">
import { CheckboxInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef<InstanceType<typeof CheckboxInput>>('checkbox-input');
function uncheck(): void {
element.value.uncheck();
}
</script>
<template>
<checkbox-input ref="checkbox-input" />
<button @click="uncheck">Uncheck the element</button>
</template><script setup>
import { CheckboxInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef('checkbox-input');
function uncheck() {
element.value.uncheck();
}
</script>
<template>
<checkbox-input ref="checkbox-input" />
<button @click="uncheck">Uncheck the element</button>
</template>validate
Programmatically trigger validation of the current value. Runs all the provided validators in order in which they are provided and returns the results.
Return type definition
type ValidationResult = {
valid: boolean;
failed: string[];
};<script setup lang="ts">
import type { ValidationFunction } from '@vuetags/inputs';
import { CheckboxInput } from '@vuetags/inputs';
import type { CheckboxModel } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef<InstanceType<typeof CheckboxInput>>('checkbox-input');
const validators: ValidationFunction[] = [
(value: CheckboxModel) => value === true || 'This field is required'
];
function validate(): void {
// If the value is false, it logs:
// { valid: false, failed: ['This field is required'] }
console.log(element.value.validate());
}
</script>
<template>
<checkbox-input ref="checkbox-input" :validators="validators" />
<button @click="validate">Validate value</button>
</template><script setup>
import { CheckboxInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef('checkbox-input');
const validators = [
(value) => value === true || 'This field is required'
];
function validate() {
// If the value is empty, it logs:
// { valid: false, failed: ['This field is required'] }
console.log(element.value.validate());
}
</script>
<template>
<checkbox-input ref="checkbox-input" :validators="validators" />
<button @click="validate">Validate value</button>
</template>