Checkbox

Lets people turn a choice on or off, or pick any number of options from a list.

<script setup lang="ts">
import { FsCheckbox } from '@fivespark/ui'
import { ref } from 'vue'

const voorwaarden = ref(false)
</script>

<template>
  <FsCheckbox v-model="voorwaarden" label="Ik ga akkoord met de algemene voorwaarden" />
</template>

Usage

<script setup lang="ts">
import { FsCheckbox } from '@fivespark/ui'
import { ref } from 'vue'

const akkoord = ref(false)
</script>

<template>
  <FsCheckbox v-model="akkoord" label="Ik ga akkoord" />
</template>

A checkbox names itself with label. In a Field, give the field no label; it adds the description and the error. Several boxes that belong together go in a FsCheckboxGroup inside a Field. Pick exactly one option with Radio; a setting that takes effect at once is a Switch.

Examples

With a description

<script setup lang="ts">
import { FsCheckbox } from '@fivespark/ui'
import { ref } from 'vue'

const kopie = ref(true)
</script>

<template>
  <FsCheckbox v-model="kopie" label="Stuur mij een kopie" description="We mailen de offerte ook naar jouw adres." class="max-w-sm" />
</template>

Group

FsCheckboxGroup holds the chosen values as an array and gives every box its name. The field supplies the question.

<script setup lang="ts">
import { FsCheckbox, FsCheckboxGroup, FsField } from '@fivespark/ui'
import { ref } from 'vue'

const contact = ref(['email'])
</script>

<template>
  <FsField label="Contact via" description="Kies alles wat van toepassing is." class="max-w-sm">
    <FsCheckboxGroup v-model="contact" name="contact">
      <FsCheckbox label="E-mail" value="email" />
      <FsCheckbox label="Telefoon" value="telefoon" />
      <FsCheckbox label="Post" value="post" />
    </FsCheckboxGroup>
  </FsField>
</template>

Horizontal group

Horizontal is for up to three short options without descriptions. Longer lists stay vertical.

<script setup lang="ts">
import { FsCheckbox, FsCheckboxGroup, FsField } from '@fivespark/ui'
import { ref } from 'vue'

const dagen = ref(['ma'])
</script>

<template>
  <FsField label="Leverdagen">
    <FsCheckboxGroup v-model="dagen" name="dagen" orientation="horizontal">
      <FsCheckbox label="Maandag" value="ma" />
      <FsCheckbox label="Woensdag" value="wo" />
      <FsCheckbox label="Vrijdag" value="vr" />
    </FsCheckboxGroup>
  </FsField>
</template>

Indeterminate

A parent box shows that only some of its children are checked. Pressing it checks the box and clears the dash.

<script setup lang="ts">
import { FsCheckbox, FsCheckboxGroup } from '@fivespark/ui'
import { computed, ref, watch } from 'vue'

const keuzes = ['email', 'telefoon', 'post']
const contact = ref(['email'])
const partial = ref(true)
const alles = computed({
  get: () => contact.value.length === keuzes.length,
  set: (checked) => { contact.value = checked ? [...keuzes] : [] },
})

watch(contact, (value) => { partial.value = value.length > 0 && value.length < keuzes.length })
</script>

<template>
  <div class="flex flex-col gap-3">
    <FsCheckbox v-model="alles" v-model:indeterminate="partial" label="Alle kanalen" />
    <FsCheckboxGroup v-model="contact" name="kanalen" aria-label="Kanalen" class="ps-6">
      <FsCheckbox label="E-mail" value="email" />
      <FsCheckbox label="Telefoon" value="telefoon" />
      <FsCheckbox label="Post" value="post" />
    </FsCheckboxGroup>
  </div>
</template>

Disabled

<script setup lang="ts">
import { FsCheckbox } from '@fivespark/ui'
</script>

<template>
  <div class="flex flex-col gap-3">
    <FsCheckbox disabled label="Factuur per post" />
    <FsCheckbox disabled :model-value="true" label="Offerte per e-mail" />
  </div>
</template>

Read-only

A read-only checkbox shows its value without letting it change. Unlike a disabled one it stays focusable and is submitted.

<script setup lang="ts">
import { FsCheckbox } from '@fivespark/ui'
</script>

<template>
  <FsCheckbox readonly :model-value="true" label="Algemene voorwaarden geaccepteerd" />
</template>

Invalid

Put the message on the field's error; the group is marked invalid with it.

<script setup lang="ts">
import { FsCheckbox, FsCheckboxGroup, FsField } from '@fivespark/ui'
import { ref } from 'vue'

const contact = ref<string[]>([])
</script>

<template>
  <FsField label="Contact via" error="Kies minstens één manier om contact op te nemen." class="max-w-sm">
    <FsCheckboxGroup v-model="contact" name="contact-fout">
      <FsCheckbox label="E-mail" value="email" />
      <FsCheckbox label="Telefoon" value="telefoon" />
    </FsCheckboxGroup>
  </FsField>
</template>

Keyboard

Key	Does
Space	Checks or unchecks the focused box
Tab	Moves to the next box

API Reference

FsCheckbox

Prop	Type	Default	Description
value	string	"on"	Submitted when checked, and its value in a group's array.
label	string		The visible name. Or the default slot, for a label with a link in it.
description	string		One short sentence under the label. Or the `description` slot.
id	string		Without a field. In a field, the box takes the field's.
invalid	boolean		Marks the box as wrong; the field says why. In a field, the box takes the field's.
required	boolean		It must be checked, as for accepting terms. Never in a group: its legend says so.
disabled	boolean		Unavailable for now. In a field, the box takes the field's.
readonly	boolean		Focusable and submitted, its value fixed. Say why in the field's description.
readonlyText	string		Replaces the hidden "alleen lezen" or "read-only" of a single read-only box.
modelValue	boolean	false	Checked, for a single box. In a group, the group's `v-model` holds it.
indeterminate	boolean	false	Shows the minus, exposed as mixed. A click clears it and checks the box.

Event	Payload	Description
update:modelValue	[value: boolean]	Sent with the new `modelValue`, for `v-model`.
update:indeterminate	[value: boolean]	Sent with the new `indeterminate`, for `v-model:indeterminate`.

Slot	Props	Description
default	any	The visible name, in place of `label`: for a label with a link in it.
description	any	One short sentence under the label, in place of `description`.

FsCheckboxGroup

Prop	Type	Default	Description
name	string		Given to every box, so the form posts `name=a&name=b`.
orientation	"vertical" | "horizontal"	"vertical"	Horizontal for up to three short options without descriptions. They stack when they do not fit.
size	"default" | "dense"		`dense` puts the options closer together; the box does not change.
invalid	boolean		Marks the group as wrong; the field says why. In a field, the group takes the field's.
required	boolean		At least one must be checked, which the form validates. Said in the legend, never on the boxes.
disabled	boolean		Unavailable for now, every box with it. In a field, the group takes the field's.
readonly	boolean		Focusable and submitted, its values fixed. Say why in the field's description.
requiredText	string		Replaces the hidden "verplicht" or "required" of a group without a field.
readonlyText	string		Replaces the hidden "alleen lezen" or "read-only" of a group without a field.
modelValue	string[]	[]	The values of the checked boxes.

Event	Payload	Description
update:modelValue	[value: string[]]	Sent with the new `modelValue`, for `v-model`.

Slot	Props	Description
default	any	The `FsCheckbox`es.