Checkbox - Vant 4

☑️ Checkbox - Interactive Selection Made Simple

🎯 Introduction

Create intuitive multiple-choice experiences with our flexible Checkbox component! Perfect for forms, settings panels, and any scenario where users need to select multiple options from a list.

📦 Installation

Get started quickly by registering the component globally via app.use. For more registration options, check out our Component Registration guide.

import { createApp } from'vue'; import { Checkbox, CheckboxGroup } from'vant'; const app = createApp(); app.use(Checkbox); app.use(CheckboxGroup);

🎨 Usage Examples

🌟 Basic Usage

Start with the simplest checkbox implementation:

import { ref } from'vue'; exportdefault { setup() { const checked = ref(true); return { checked, }; }, };

🚫 Disabled State

Prevent user interaction when needed:

🔷 Custom Shape

Switch between round and square styles to match your design:

import { ref } from'vue'; exportdefault { setup() { const checked = ref(['a', 'b']); return { checked }; }, };

🎨 Custom Color

Make checkboxes match your brand colors:

📏 Custom Icon Size

Adjust the checkbox size to fit your layout perfectly:

🖼️ Custom Icon

Create unique checkbox experiences with custom icons:

import { ref } from'vue'; exportdefault { setup() { const checked = ref(true); return { checked, activeIcon: 'https://fastly.jsdelivr.net/npm/@vant/assets/user-active.png', inactiveIcon: 'https://fastly.jsdelivr.net/npm/@vant/assets/user-inactive.png', }; }, };

⬅️ Left Label

Position labels on the left side for better layout flexibility:

🔒 Disable Label Click

Prevent accidental selections by disabling label clicks:

📋 Checkbox Group

Manage multiple checkboxes effortlessly with group functionality:

import { ref } from'vue'; exportdefault { setup() { const checked = ref(['a', 'b']); return { checked }; }, };

↔️ Horizontal Layout

Display checkboxes in a horizontal row for compact layouts:

import { ref } from'vue'; exportdefault { setup() { const checked = ref([]); return { checked }; }, };

🔢 Maximum Selection Limit

Control how many options users can select:

🔄 Toggle All Functionality

Provide convenient select-all and deselect-all controls:

import { ref } from'vue'; exportdefault { setup() { const checked = ref([]); const checkboxGroup = ref(null); constcheckAll = () => { checkboxGroup.value.toggleAll(true); } consttoggleAll = () => { checkboxGroup.value.toggleAll(); }, return { checked, checkAll, toggleAll, checkboxGroup, }; }, };

📱 Inside a Cell

Integrate checkboxes seamlessly within cell components:

import { ref, onBeforeUpdate } from'vue'; exportdefault { setup() { const checked = ref([]); const checkboxRefs = ref([]); consttoggle = (index) => { checkboxRefs.value[index].toggle(); }; onBeforeUpdate(() => { checkboxRefs.value = []; }); return { list: ['a', 'b'], toggle, checked, checkboxRefs, }; }, };

⚡ Indeterminate State

Show partial selection states for better user feedback:

import { ref } from'vue'; exportdefault { setup() { const list = ['a', 'b', 'c', 'd'] const isCheckAll = ref(false); const checkedResult = ref(['a', 'b', 'd']); const isIndeterminate = ref(true); constcheckAllChange = (val: boolean) => { checkedResult.value = val ? list : [] isIndeterminate.value = false } constcheckedResultChange = (value: string[]) => { const checkedCount = value.length isCheckAll.value = checkedCount === list.length isIndeterminate.value = checkedCount > 0 && checkedCount < list.length } return { list, isCheckAll, checkedResult, checkAllChange, isIndeterminate, checkedResultChange }; }, };

🔧 API Reference

🎛️ Checkbox Props

Configure your checkbox behavior with these powerful options:

Attribute	Description	Type	Default
v-model	Check status	boolean	false
name	Checkbox name, usually a unique string or number	any	-
shape	Can be set to square	string	round
disabled	Disable checkbox	boolean	false
label-disabled	Whether to disable label click	boolean	false
label-position	Can be set to left	string	right
icon-size	Icon size	*number	string*
checked-color	Checked color	string	#1989fa

| bind-group | Whether to bind with CheckboxGroup | boolean | true | | indeterminate | Whether indeterminate status | boolean | false |

📋 CheckboxGroup Props

Manage multiple checkboxes with these group-level configurations:

Attribute	Description	Type	Default
v-model	Names of all checked checkboxes	any[]	-
disabled	Whether to disable all checkboxes	boolean	false
max	Maximum amount of checked options	*number	string*
direction	Direction, can be set to horizontal	string	vertical
icon-size	Icon size of all checkboxes	*number	string*
checked-color	Checked color of all checkboxes	string	#1989fa

| shape v4.6.3 | Can be set to square | string | round |

📡 Checkbox Events

Listen to user interactions and state changes:

Event	Description	Parameters
change	Emitted when value changed	checked: boolean
click	Emitted when the checkbox is clicked	event: MouseEvent

📡 CheckboxGroup Events

Track group-level changes:

Event	Description	Parameters
change	Emitted when value changed	names: any[]

🎰 Checkbox Slots

Customize checkbox appearance with flexible slots:

Name	Description	SlotProps
default	Custom label	{ checked: boolean, disabled: boolean }
icon	Custom icon	{ checked: boolean, disabled: boolean }

⚙️ CheckboxGroup Methods

Use ref to get CheckboxGroup instance and call instance methods.

Name	Description	Attribute	Return value
toggleAll	Toggle check status of all checkboxes	*options?: boolean	object*

toggleAll Usage

import { ref } from'vue'; import type { CheckboxGroupInstance } from'vant'; const checkboxGroupRef = ref<CheckboxGroupInstance>(); // Toggle all checkboxGroup.value?.toggleAll(); // Select all checkboxGroup.value?.toggleAll(true); // Unselect all checkboxGroup.value?.toggleAll(false); // Toggle all, skip disabled checkboxGroup.value?.toggleAll({ skipDisabled: true, }); // Select all, skip disabled checkboxGroup.value?.toggleAll({ checked: true, skipDisabled: true, });

⚙️ Checkbox Methods

Control individual checkboxes programmatically:

Name	Description	Attribute	Return value
toggle	Toggle check status	checked?: boolean	-

📝 Types

Access comprehensive TypeScript definitions for better development experience:

importtype { CheckboxProps, CheckboxShape, CheckboxInstance, CheckboxLabelPosition, CheckboxGroupProps, CheckboxGroupInstance, CheckboxGroupDirection, CheckboxGroupToggleAllOptions, } from'vant';

CheckboxInstance and CheckboxGroupInstance is the type of component instance:

import { ref } from'vue'; importtype { CheckboxInstance, CheckboxGroupInstance } from'vant'; const checkboxRef = ref<CheckboxInstance>(); const checkboxGroupRef = ref<CheckboxGroupInstance>(); checkboxRef.value?.toggle(); checkboxGroupRef.value?.toggleAll();

🎨 Theming

🎯 CSS Variables

Customize the checkbox appearance to match your design system perfectly:

Name	Default Value	Description
--van-checkbox-size	20px	-
--van-checkbox-border-color	var(--van-gray-5)	-
--van-checkbox-duration	var(--van-duration-fast)	-
--van-checkbox-label-margin	var(--van-padding-xs)	-
--van-checkbox-label-color	var(--van-text-color)	-
--van-checkbox-checked-icon-color	var(--van-primary-color)	-
--van-checkbox-disabled-icon-color	var(--van-gray-5)	-
--van-checkbox-disabled-label-color	var(--van-text-color-3)	-
--van-checkbox-disabled-background	var(--van-border-color)	-

📚 Related Docs

Explore more components and resources to enhance your development experience:

Form Components

• Radio - Single selection from multiple options
• Switch - Toggle between two states
• Field - Input field with validation
• Form - Complete form solution with validation

Layout & Display

• Cell - List item container
• List - Scrollable list component
• Grid - Flexible grid layout system

Development Resources

• ConfigProvider - Global configuration and theming
• Locale - Internationalization support

External Links

• Vue 3 Template Refs - Learn about component references
• Accessibility Guidelines - Form accessibility best practices