N Checkbox

n-checkbox Component

The n-checkbox component is used for binary selections and multiple selections within groups. It supports indeterminate states, custom checked/unchecked values, and integrates well with grid layouts for complex form scenarios.

When to Use

Use n-checkbox when you need to:

• Allow users to select one or more options from a list
• Create binary toggle controls (yes/no, on/off)
• Implement "select all" functionality with indeterminate state
• Build grid-based selection interfaces
• Collect multiple values in forms
• Create controlled checkbox states

Basic Usage

Basic Checkbox

<template>
  <n-checkbox v-model:checked="checked">
    Checkbox Label
  </n-checkbox>
</template>

<script setup>
import { ref } from 'vue'

const checked = ref(false)
</script>

Checkbox Group

<template>
  <n-checkbox-group v-model:value="cities">
    <n-space item-style="display: flex;">
      <n-checkbox value="Beijing" label="Beijing" />
      <n-checkbox value="Shanghai" label="Shanghai" />
      <n-checkbox value="Guangzhou" label="Guangzhou" />
      <n-checkbox value="Shenzhen" label="Shenzhen" />
    </n-space>
  </n-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'

const cities = ref(['Beijing'])
</script>

Different Sizes

<template>
  <n-space item-style="display: flex;" align="center">
    <n-checkbox size="small" label="Small" />
    <n-checkbox size="medium" label="Medium" />
    <n-checkbox size="large" label="Large" />
  </n-space>
</template>

API Reference

Checkbox Props

CheckboxGroup Props

Events

Checkbox Events

CheckboxGroup Events

Slots

Checkbox Slots

CheckboxGroup Slots

Methods

Common Patterns

Indeterminate State (Select All)

<template>
  <n-space item-style="display: flex;" vertical>
    <n-checkbox
      v-model:checked="allChecked"
      :indeterminate="indeterminate"
      @update:checked="handleAllChecked"
    >
      Select All
    </n-checkbox>
    <n-checkbox-group v-model:value="cities">
      <n-space item-style="display: flex;">
        <n-checkbox value="Beijing" label="Beijing" />
        <n-checkbox value="Shanghai" label="Shanghai" />
        <n-checkbox value="Guangzhou" label="Guangzhou" />
        <n-checkbox value="Shenzhen" label="Shenzhen" />
      </n-space>
    </n-checkbox-group>
  </n-space>
</template>

<script setup>
import { ref, computed, watch } from 'vue'

const allCities = ['Beijing', 'Shanghai', 'Guangzhou', 'Shenzhen']
const cities = ref([])

const allChecked = computed({
  get: () => cities.value.length === allCities.length,
  set: (val) => {
    cities.value = val ? [...allCities] : []
  }
})

const indeterminate = computed(() => {
  return cities.value.length > 0 && cities.value.length < allCities.length
})

const handleAllChecked = (checked) => {
  cities.value = checked ? [...allCities] : []
}
</script>

Grid Layout

<template>
  <n-checkbox-group v-model:value="selected">
    <n-grid :y-gap="8" :cols="2">
      <n-gi>
        <n-checkbox value="option1" label="Option 1" />
      </n-gi>
      <n-gi>
        <n-checkbox value="option2" label="Option 2" />
      </n-gi>
      <n-gi>
        <n-checkbox value="option3" label="Option 3" />
      </n-gi>
      <n-gi>
        <n-checkbox value="option4" label="Option 4" />
      </n-gi>
    </n-grid>
  </n-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'

const selected = ref([])
</script>

Custom Checked Values

<template>
  <n-checkbox
    v-model:checked="status"
    checked-value="active"
    unchecked-value="inactive"
  >
    Status: {{ status }}
  </n-checkbox>
</template>

<script setup>
import { ref } from 'vue'

const status = ref('inactive')
</script>

Controlled Checkbox

<template>
  <n-space align="center" item-style="display: flex;">
    <n-checkbox :checked="checked">
      Controlled Checkbox
    </n-checkbox>
    <n-switch v-model:value="checked" />
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const checked = ref(false)
</script>

Min/Max Selection Limits

<template>
  <n-checkbox-group v-model:value="selected" :min="1" :max="3">
    <n-space item-style="display: flex;">
      <n-checkbox value="1" label="Option 1" />
      <n-checkbox value="2" label="Option 2" />
      <n-checkbox value="3" label="Option 3" />
      <n-checkbox value="4" label="Option 4" />
    </n-space>
  </n-checkbox-group>
  <p>Select between 1 and 3 options (currently: {{ selected.length }})</p>
</template>

<script setup>
import { ref } from 'vue'

const selected = ref(['1'])
</script>

Using Methods via Ref

<template>
  <n-space item-style="display: flex; align-items: center;">
    <n-button @click="handleClick">
      Focus then blur in 1 second
    </n-button>
    <n-checkbox ref="checkboxRef" label="Controlled via ref" />
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const checkboxRef = ref(null)

const handleClick = () => {
  checkboxRef.value?.focus()
  setTimeout(() => {
    checkboxRef.value?.blur()
  }, 1000)
}
</script>

Event Handling

<template>
  <n-space item-style="display: flex;" vertical>
    <n-checkbox
      v-model:checked="checked"
      label="Event Demo"
      @update:checked="handleCheckedChange"
    />
    <n-checkbox-group v-model:value="selected" @update:value="handleGroupChange">
      <n-space item-style="display: flex;">
        <n-checkbox value="A" label="A" />
        <n-checkbox value="B" label="B" />
      </n-space>
    </n-checkbox-group>
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const checked = ref(false)
const selected = ref([])

const handleCheckedChange = (val) => {
  console.log('Checkbox changed:', val)
}

const handleGroupChange = (value, meta) => {
  console.log('Group changed:', value, meta.actionType, meta.value)
}
</script>

Best Practices

1. Use v-model:checked for single checkbox: For cleaner code when working with a single checkbox.

2. Use n-checkbox-group for multiple related options: This provides better value management and enables min/max constraints.

3. Implement indeterminate state for "select all": Use the indeterminate prop to show partial selection state.

4. Use custom values for non-boolean data: When your data model uses specific values instead of boolean, use checked-value and unchecked-value.

5. Set focusable: false for click-only interactions: When keyboard focus is not needed, disable focusability.

6. Use min and max for validation: Enforce selection constraints at the group level for better UX.

7. Leverage grid layouts for complex forms: Combine with n-grid for multi-column checkbox layouts.

8. Handle events for side effects: Use @update:checked and @update:value for triggering actions on selection changes.