Appearance

VfCheckboxes ​

Basic ​

A checkbox group defined with items as a plain array. Each value is used as both the label and the submitted value.

Fruits
vue
<VfCheckboxes
  name="fruits"
  label="Fruits"
  :items="['Apple', 'Banana', 'Cherry']"
/>
vue
<template>
  <VfCheckboxes
    name="fruits"
    label="Fruits"
    :items="['Apple', 'Banana', 'Cherry']"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  fruits: {
    type: 'checkboxes',
    label: 'Fruits',
    items: ['Apple', 'Banana', 'Cherry'],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Plain Object ​
When items is a key-value object, keys become the submitted values and values become the labels.
Favorite colors
vue
<VfCheckboxes name="colors" :items="{
  red: 'Red',
  green: 'Green',
  blue: 'Blue',
}" />
vue
<template>
  <VfCheckboxes
    name="colors"
    label="Favorite colors"
    :items="{ red: 'Red', green: 'Green', blue: 'Blue' }"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  colors: {
    type: 'checkboxes',
    label: 'Favorite colors',
    items: {
      red: 'Red',
      green: 'Green',
      blue: 'Blue',
    },
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Object Array ​
When items is an array of objects, use itemLabel to specify which property holds the display text. Without itemValue, the submitted value is the entire object.
Sizes
vue
<VfCheckboxes
  name="sizes"
  item-label="label"
  :items="[
    { value: 's', label: 'Small' },
    { value: 'm', label: 'Medium' },
    { value: 'l', label: 'Large' },
  ]"
/>
vue
<template>
  <VfCheckboxes
    name="sizes"
    label="Sizes"
    item-label="label"
    :items="[
      { value: 's', label: 'Small' },
      { value: 'm', label: 'Medium' },
      { value: 'l', label: 'Large' },
    ]"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  sizes: {
    type: 'checkboxes',
    label: 'Sizes',
    itemLabel: 'label',
    items: [
      { value: 's', label: 'Small' },
      { value: 'm', label: 'Medium' },
      { value: 'l', label: 'Large' },
    ],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Use itemValue to extract a specific property as the submitted value instead of the whole object:
Sizes
vue
<VfCheckboxes
  name="sizes"
  item-label="label"
  item-value="value"
  :items="[
    { value: 's', label: 'Small' },
    { value: 'm', label: 'Medium' },
    { value: 'l', label: 'Large' },
  ]"
/>
vue
<template>
  <VfCheckboxes
    name="sizes"
    label="Sizes"
    item-label="label"
    item-value="value"
    :items="[
      { value: 's', label: 'Small' },
      { value: 'm', label: 'Medium' },
      { value: 'l', label: 'Large' },
    ]"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  sizes: {
    type: 'checkboxes',
    label: 'Sizes',
    itemLabel: 'label',
    itemValue: 'value',
    items: [
      { value: 's', label: 'Small' },
      { value: 'm', label: 'Medium' },
      { value: 'l', label: 'Large' },
    ],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Async Function ​
The items prop accepts a function that returns a promise. Vueform handles the loading state automatically while the function resolves.
Countries
vue
<VfCheckboxes
  name="countries"
  :items="async () => {
    const { data } = await $http.get(
      '/data/countries.json'
    )
    return data
  }"
/>
vue
<script setup lang="ts">
import { useHttp } from '@vueform/ui'

const $http = useHttp()
</script>

<template>
  <VfCheckboxes
    name="countries"
    label="Countries"
    item-label="name"
    item-value="code"
    :items="async () => {
      const { data } = await $http.get(
        '/data/countries.json'
      )
      return data
    }"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm, useHttp } from '@vueform/ui'

const $http = useHttp()

const items = async () => {
  const { data } = await $http.get('/data/countries.json')
  return data
}

const schema = defineSchema({
  countries: {
    type: 'checkboxes',
    label: 'Countries',
    itemLabel: 'name',
    itemValue: 'code',
    items,
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Endpoint ​
The items prop also accepts a URL string. Vueform sends a request and uses the response as items. Use transformItems to reshape the response if the data isn't at the top level.
Countries
vue
<VfCheckboxes name="countries" items="/data/countries.json" />
vue
<template>
  <VfCheckboxes
    name="countries"
    label="Countries"
    item-label="name"
    item-value="code"
    items="/data/countries.json"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  countries: {
    type: 'checkboxes',
    label: 'Countries',
    itemLabel: 'name',
    itemValue: 'code',
    items: '/data/countries.json',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Conditional Items ​
The itemConditions prop specifies which property on each item object holds conditions that control its visibility. See Conditions on Items for the full syntax.
Features
vue
<VfCheckboxes
  name="features"
  item-conditions="conditions"
  :items="[
    { value: 'basic', label: 'Basic' },
    { value: 'export', label: 'Export' },
    {
      value: 'analytics',
      label: 'Analytics',
      conditions: [['premium', '==', true]],
    },
  ]"
/>
vue
<template>
  <VfCheckbox name="premium" text="I have a premium account" />
  <VfCheckboxes
    name="features"
    label="Features"
    item-label="label"
    item-value="value"
    item-conditions="conditions"
    :items="[
      { value: 'basic', label: 'Basic' },
      { value: 'export', label: 'Export' },
      {
        value: 'analytics',
        label: 'Analytics',
        conditions: [['premium', '==', true]],
      },
    ]"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  premium: {
    type: 'checkbox',
    text: 'I have a premium account',
  },
  features: {
    type: 'checkboxes',
    label: 'Features',
    itemLabel: 'label',
    itemValue: 'value',
    itemConditions: 'conditions',
    items: [
      { value: 'basic', label: 'Basic' },
      { value: 'export', label: 'Export' },
      {
        value: 'analytics',
        label: 'Analytics',
        conditions: [['premium', '==', true]],
      },
    ],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Disabled Items ​
The itemDisabled prop specifies which property on each item object determines whether it is disabled.
Plans
vue
<VfCheckboxes
  name="plans"
  item-disabled="disabled"
  :items="[
    { value: 'free', label: 'Free' },
    { value: 'pro', label: 'Pro' },
    {
      value: 'enterprise',
      label: 'Enterprise',
      disabled: true,
    },
  ]"
/>
vue
<template>
  <VfCheckbox name="premium" text="I have a premium account" />
  <VfCheckboxes
    name="plans"
    label="Plans"
    item-label="label"
    item-value="value"
    item-disabled="disabled"
    :items="[
      { value: 'free', label: 'Free' },
      { value: 'pro', label: 'Pro' },
      {
        value: 'enterprise',
        label: 'Enterprise',
        disabled: [['premium', '!=', true]],
      },
    ]"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  premium: {
    type: 'checkbox',
    text: 'I have a premium account',
  },
  plans: {
    type: 'checkboxes',
    label: 'Plans',
    itemLabel: 'label',
    itemValue: 'value',
    itemDisabled: 'disabled',
    items: [
      { value: 'free', label: 'Free' },
      { value: 'pro', label: 'Pro' },
      {
        value: 'enterprise',
        label: 'Enterprise',
        disabled: [['premium', '!=', true]],
      },
    ],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Groups ​
The groupLabel and groupChildren props enable rendering items in labeled groups. Each group object holds a label and a nested list of items.
Permissions
Content
Users
vue
<VfCheckboxes
  name="permissions"
  group-label="category"
  group-children="items"
  :items="[
    {
      category: 'Content',
      items: [
        { value: 'create', label: 'Create' },
        { value: 'edit', label: 'Edit' },
        { value: 'delete', label: 'Delete' },
      ],
    },
    {
      category: 'Users',
      items: [
        { value: 'invite', label: 'Invite' },
        { value: 'manage', label: 'Manage' },
      ],
    },
  ]"
/>
vue
<template>
  <VfCheckboxes
    name="permissions"
    label="Permissions"
    item-label="label"
    item-value="value"
    group-label="category"
    group-children="items"
    :items="[
      {
        category: 'Content',
        items: [
          { value: 'create', label: 'Create' },
          { value: 'edit', label: 'Edit' },
          { value: 'delete', label: 'Delete' },
        ],
      },
      {
        category: 'Users',
        items: [
          { value: 'invite', label: 'Invite' },
          { value: 'manage', label: 'Manage' },
        ],
      },
    ]"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  permissions: {
    type: 'checkboxes',
    label: 'Permissions',
    itemLabel: 'label',
    itemValue: 'value',
    groupLabel: 'category',
    groupChildren: 'items',
    items: [
      {
        category: 'Content',
        items: [
          { value: 'create', label: 'Create' },
          { value: 'edit', label: 'Edit' },
          { value: 'delete', label: 'Delete' },
        ],
      },
      {
        category: 'Users',
        items: [
          { value: 'invite', label: 'Invite' },
          { value: 'manage', label: 'Manage' },
        ],
      },
    ],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Conditional Groups ​
The groupConditions prop specifies which property on each group object holds conditions that control its visibility. Groups whose conditions are not met are hidden entirely. See Conditions on Items for the full syntax.
Build tools
Active
Archived
vue
<VfCheckboxes
  name="tools"
  group-conditions="conditions"
  :items="[
    {
      category: 'Active',
      tools: [
        { value: 'vite', label: 'Vite' },
        { value: 'esbuild', label: 'ESBuild' },
      ],
    },
    {
      category: 'Archived',
      tools: [
        { value: 'gulp', label: 'Gulp' },
        { value: 'grunt', label: 'Grunt' },
      ],
      conditions: [
        ['showArchived', '==', true],
      ],
    },
  ]"
/>
vue
<template>
  <VfCheckbox
    name="showArchived"
    text="Show archived tools"
  />
  <VfCheckboxes
    name="tools"
    label="Build tools"
    item-label="label"
    item-value="value"
    group-label="category"
    group-children="tools"
    group-conditions="conditions"
    :items="[
      {
        category: 'Active',
        tools: [
          { value: 'vite', label: 'Vite' },
          { value: 'esbuild', label: 'ESBuild' },
        ],
      },
      {
        category: 'Archived',
        conditions: [['showArchived', '==', true]],
        tools: [
          { value: 'gulp', label: 'Gulp' },
          { value: 'grunt', label: 'Grunt' },
        ],
      },
    ]"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  showArchived: {
    type: 'checkbox',
    text: 'Show archived tools',
  },
  tools: {
    type: 'checkboxes',
    label: 'Build tools',
    itemLabel: 'label',
    itemValue: 'value',
    groupLabel: 'category',
    groupChildren: 'tools',
    groupConditions: 'conditions',
    items: [
      {
        category: 'Active',
        tools: [
          { value: 'vite', label: 'Vite' },
          { value: 'esbuild', label: 'ESBuild' },
        ],
      },
      {
        category: 'Archived',
        conditions: [['showArchived', '==', true]],
        tools: [
          { value: 'gulp', label: 'Gulp' },
          { value: 'grunt', label: 'Grunt' },
        ],
      },
    ],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Hint Text ​
The hint prop displays advisory text below the input. Use it to provide contextual guidance to the user.
Notifications
vue
<VfCheckboxes
  name="notifications"
  hint="You can change your preferences at any time."
/>
vue
<template>
  <VfCheckboxes
    name="notifications"
    label="Notifications"
    :items="{ email: 'Email', sms: 'SMS', push: 'Push' }"
    hint="You can change your preferences at any time."
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  notifications: {
    type: 'checkboxes',
    label: 'Notifications',
    items: { email: 'Email', sms: 'SMS', push: 'Push' },
    hint: 'You can change your preferences at any time.',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Help Text ​
The help prop displays advisory text below the label. Unlike hint (which appears below the input), help is positioned directly under the label.
Interests
Select the topics you're interested in.
vue
<VfCheckboxes
  name="interests"
  help="Select the topics you're interested in."
/>
vue
<template>
  <VfCheckboxes
    name="interests"
    label="Interests"
    :items="{ tech: 'Tech', design: 'Design', business: 'Business' }"
    help="Select the topics you're interested in."
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  interests: {
    type: 'checkboxes',
    label: 'Interests',
    items: { tech: 'Tech', design: 'Design', business: 'Business' },
    help: "Select the topics you're interested in.",
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Stacked ​
The stacked prop renders the checkboxes in a horizontal row instead of a vertical list.
Options
vue
<VfCheckboxes
  name="options"
  :items="{ a: 'Option A', b: 'Option B', c: 'Option C' }"
  stacked
/>
vue
<template>
  <VfCheckboxes
    name="options"
    label="Options"
    :items="{ a: 'Option A', b: 'Option B', c: 'Option C' }"
    stacked
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  options: {
    type: 'checkboxes',
    label: 'Options',
    items: { a: 'Option A', b: 'Option B', c: 'Option C' },
    stacked: true,
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Disabled ​
The disabled prop disables the entire checkbox group. It also accepts conditions.
Disabled
vue
<VfCheckboxes name="disabled" disabled />
vue
<template>
  <VfCheckboxes
    name="disabled"
    label="Disabled"
    :items="{ a: 'Option A', b: 'Option B', c: 'Option C' }"
    :default="['a']"
    disabled
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  disabled: {
    type: 'checkboxes',
    label: 'Disabled',
    items: { a: 'Option A', b: 'Option B', c: 'Option C' },
    default: ['a'],
    disabled: true,
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Released under the MIT License.
Copyright © 2022-present Adam Berecz