vant/src/checkbox/README.md

Checkbox

Intro

A group of options for multiple choices.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

import { createApp } from 'vue';
import { Checkbox, CheckboxGroup } from 'vant';

const app = createApp();
app.use(Checkbox);
app.use(CheckboxGroup);

Usage

Basic Usage

<van-checkbox v-model="checked">Checkbox</van-checkbox>

import { ref } from 'vue';

export default {
  setup() {
    const checked = ref(true);
    return {
      checked,
    };
  },
};

Disabled

<van-checkbox v-model="checked" disabled>Checkbox</van-checkbox>

Custom Shape

<van-checkbox v-model="checked" shape="square">Checkbox</van-checkbox>

Custom Color

<van-checkbox v-model="checked" checked-color="#ee0a24">Checkbox</van-checkbox>

Custom Icon Size

<van-checkbox v-model="checked" icon-size="24px">Checkbox</van-checkbox>

Custom Icon

Use icon slot to custom icon.

<van-checkbox v-model="checked">
  customize icon
  <template #icon="props">
    <img class="img-icon" :src="props.checked ? activeIcon : inactiveIcon" />
  </template>
</van-checkbox>

<style>
  .img-icon {
    height: 20px;
  }
</style>

import { ref } from 'vue';

export default {
  setup() {
    const checked = ref(true);
    return {
      checked,
      activeIcon: 'https://img.yzcdn.cn/vant/user-active.png',
      inactiveIcon: 'https://img.yzcdn.cn/vant/user-inactive.png',
    };
  },
};

Disable Label Click

<van-checkbox v-model="checked" label-disabled>Checkbox</van-checkbox>

Checkbox Group

When Checkboxes are inside a CheckboxGroup, the checked checkboxes's name is an array and bound with CheckboxGroup by v-model.

<van-checkbox-group v-model="checked">
  <van-checkbox name="a">Checkbox a</van-checkbox>
  <van-checkbox name="b">Checkbox b</van-checkbox>
</van-checkbox-group>

import { ref } from 'vue';

export default {
  setup() {
    const checked = ref(['a', 'b']);
    return { checked };
  },
};

Horizontal

<van-checkbox-group v-model="checked" direction="horizontal">
  <van-checkbox name="a">Checkbox a</van-checkbox>
  <van-checkbox name="b">Checkbox b</van-checkbox>
</van-checkbox-group>

import { ref } from 'vue';

export default {
  setup() {
    const checked = ref([]);
    return { checked };
  },
};

Maximum amount of checked options

<van-checkbox-group v-model="checked" :max="2">
  <van-checkbox name="a">Checkbox a</van-checkbox>
  <van-checkbox name="b">Checkbox b</van-checkbox>
  <van-checkbox name="c">Checkbox c</van-checkbox>
</van-checkbox-group>

Toggle All

<van-checkbox-group v-model="checked" ref="checkboxGroup">
  <van-checkbox name="a">Checkbox a</van-checkbox>
  <van-checkbox name="b">Checkbox b</van-checkbox>
  <van-checkbox name="c">Checkbox c</van-checkbox>
</van-checkbox-group>

<van-button type="primary" @click="checkAll">Check All</van-button>
<van-button type="primary" @click="toggleAll">Toggle All</van-button>

import { ref } from 'vue';

export default {
  setup() {
    const checked = ref([]);
    const checkboxGroup = ref(null);

    const checkAll = () => {
      checkboxGroup.value.toggleAll(true);
    }
    const toggleAll = () => {
      checkboxGroup.value.toggleAll();
    },

    return {
      checked,
      checkAll,
      toggleAll,
      checkboxGroup,
    };
  },
};

Inside a Cell

<van-checkbox-group v-model="checked">
  <van-cell-group>
    <van-cell
      v-for="(item, index) in list"
      clickable
      :key="item"
      :title="`Checkbox ${item}`"
      @click="toggle(index)"
    >
      <template #right-icon>
        <van-checkbox
          :name="item"
          :ref="el => checkboxRefs[index] = el"
          @click.stop
        />
      </template>
    </van-cell>
  </van-cell-group>
</van-checkbox-group>

import { ref, onBeforeUpdate } from 'vue';

export default {
  setup() {
    const checked = ref([]);
    const checkboxRefs = ref([]);
    const toggle = (index) => {
      checkboxRefs.value[index].toggle();
    };

    onBeforeUpdate(() => {
      checkboxRefs.value = [];
    });

    return {
      list: ['a', 'b'],
      toggle,
      checked,
      checkboxRefs,
    };
  },
};

API

Checkbox Props

Attribute	Description	Type	Default
v-model	Check status	boolean	false
name	Checkbox name	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	20px
checked-color	Checked color	string	#1989fa
bind-group	Whether to bind with CheckboxGroup	boolean	true

CheckboxGroup Props

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	0(Unlimited)
direction	Direction, can be set to horizontal	string	vertical
icon-size	Icon size of all checkboxes	number | string	20px
checked-color	Checked color of all checkboxes	string	#1989fa

Checkbox Events

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

CheckboxGroup Events

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

Checkbox Slots

Name	Description	SlotProps
default	Custom label	-
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

const { checkboxGroup } = this.$refs;

// Toggle all
checkboxGroup.toggleAll();
// Select all
checkboxGroup.toggleAll(true);
// Unselect all
checkboxGroup.toggleAll(false);

// Toggle all, skip disabled
checkboxGroup.toggleAll({
  skipDisabled: true,
});
// Select all, skip disabled
checkboxGroup.toggleAll({
  checked: true,
  skipDisabled: true,
});

Checkbox Methods

Use ref to get Checkbox instance and call instance methods.

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

CSS Variables

The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.

Name	Default Value	Description
--van-checkbox-size	20px	-
--van-checkbox-border-color	var(--van-gray-5)	-
--van-checkbox-transition-duration	var(--van-animation-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-gray-5)	-
--van-checkbox-disabled-background-color	var(--van-border-color)	-