Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

Checkbox

A native checkbox for boolean or array models, including mixed state.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add checkbox

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import Checkbox from './components/ui/checkbox/Checkbox.vue'

const accepted = ref(false)
</script>

<template>
  <Checkbox v-model="accepted" required>Accept the terms</Checkbox>
</template>

The underlying input retains native form, label, and keyboard behavior.

When to use it

Terms confirmation

Require a single explicit acknowledgement before submitting a form.

Multiple preferences

Bind several native checkboxes to one array of selected values.

More examples

Required acknowledgement

The wrapping label enlarges the clickable text target.

Required acknowledgement
<script setup lang="ts">
import { ref } from 'vue'
import Checkbox from './components/ui/checkbox/Checkbox.vue'

const accepted = ref(false)
</script>
<template>
  <Checkbox v-model="accepted" name="terms" required>I accept the terms</Checkbox>
</template>

Notification channels

Array mode emits a new array when a choice changes.

Notification channels
<script setup lang="ts">
import { ref } from 'vue'
import Checkbox from './components/ui/checkbox/Checkbox.vue'

const channels = ref<string[]>(['email'])
</script>
<template>
  <Checkbox v-model="channels" value="email" name="channel">Email</Checkbox>
  <Checkbox v-model="channels" value="sms" name="channel">Text message</Checkbox>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Checkbox

Complete API for Checkbox
NameType or signatureDefaultWhat it does
valuepropT | undefinedNot setValue represented by this control or option.
indeterminatepropboolean | undefinedNot setShow a mixed state when the choice is partly selected.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
modelValuemodelboolean | T[] | undefinedfalseCurrent value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: boolean | T[]]—Requests a new model value from the parent.
defaultslot(() => unknown) | undefinedOptionalContent shown inside Checkbox.
errorslot((props: { message: string; messages: string[]; }) => unknown) | undefinedOptionalContent for the error area of Checkbox.
elementexposedHTMLInputElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
Public type definitions
Public types
// packages/frameworks/vue/components/checkbox/types.ts
// ------- TYPES -------

export interface CheckboxProps<T = string> {
  value?: T
  indeterminate?: boolean
  invalid?: boolean
}

Implementation notes

  • Use scalar string values when native form submission matters.
  • For a select-all control, derive indeterminate from the selected items and update it after each change.

Accessibility and localization

  • Give each checkbox a wrapping or associated label. Native Space, focus, and checked semantics are preserved.

Source contract and editing guidance