🌏 Translated with the assistance of DeepSeek and ChatGPT

Checkbox

This is for multiple choices.

Basic Usage

For the Checkbox component, passing modelValue puts it in controlled mode. Not passing it or passing undefined puts it in uncontrolled mode, where you can pass the defaultValue property as the default value.

Checkbox has two style variants: normal mode (normal, default) and retro mode (retro). The retro mode style is a tribute to early game UI.

Basic Checkbox

Uncontrolled

Set Label By Prop

Retro Style

Retro Style Checked

<template>
	<px-space>
		<px-checkbox v-model="checked">Basic Checkbox</px-checkbox>
		<px-checkbox :default-value="true">Uncontrolled</px-checkbox>
		<px-checkbox label="Set Label By Prop"></px-checkbox>
		<px-checkbox variant="retro">Retro Style</px-checkbox>
		<px-checkbox variant="retro" :default-value="true">Retro Style Checked</px-checkbox>
	</px-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const checked = ref(false)
</script>

Disabled and Read-only States

For the Checkbox component, use readonly to set it as read-only and disabled to set it as disabled. In both cases, the internal <input> will be set to disabled, and the difference between them is almost only in styling.

Checked

Unchecked

Checked Readonly

Unchecked Readonly

Checked

Unchecked

Checked Readonly

Unchecked Readonly

<template>
	<px-space direction="vertical">
		<px-space>
			<px-checkbox disabled :default-value="true">Checked</px-checkbox>
			<px-checkbox disabled>Unchecked</px-checkbox>
			<px-checkbox readonly :default-value="true">Checked Readonly</px-checkbox>
			<px-checkbox readonly>Unchecked Readonly</px-checkbox>
		</px-space>
		<px-space>
			<px-checkbox variant="retro" disabled :default-value="true">Checked</px-checkbox>
			<px-checkbox variant="retro" disabled>Unchecked</px-checkbox>
			<px-checkbox variant="retro" readonly :default-value="true">Checked Readonly</px-checkbox>
			<px-checkbox variant="retro" readonly>Unchecked Readonly</px-checkbox>
		</px-space>
	</px-space>
</template>

Checkbox Group

You can combine CheckboxGroup and Checkbox to form a checkbox group.

The value of CheckboxGroup is an array composed of the value of selected Checkbox components.

Similarly, CheckboxGroup enters controlled mode when modelValue is passed. Not passing it or passing undefined puts it in uncontrolled mode, where you can pass the defaultValue property as the default value.

Abigail

Harvey

Leah

Maru

Elliott

Haley

Penny

Sebastian

Retro Style

Dwarf

Krobus

Readonly

Sam

Shane

Disabled

Alex

Clint

<template>
	<px-space direction="vertical">
		<px-checkbox-group v-model="group">
			<px-checkbox value="Abigail">Abigail</px-checkbox>
			<px-checkbox value="Harvey">Harvey</px-checkbox>
			<px-checkbox value="Leah">Leah</px-checkbox>
			<px-checkbox value="Maru">Maru</px-checkbox>
		</px-checkbox-group>
		<px-checkbox-group :default-value="['Elliott']">
			<px-checkbox value="Elliott">Elliott</px-checkbox>
			<px-checkbox value="Haley">Haley</px-checkbox>
			<px-checkbox value="Penny">Penny</px-checkbox>
			<px-checkbox value="Sebastian">Sebastian</px-checkbox>
		</px-checkbox-group>
		<h4>Retro Style</h4>
		<px-checkbox-group :default-value="['Dwarf']" variant="retro">
			<px-checkbox value="Dwarf">Dwarf</px-checkbox>
			<px-checkbox value="Krobus">Krobus</px-checkbox>
		</px-checkbox-group>
		<h4>Readonly</h4>
		<px-checkbox-group :default-value="['Sam']" readonly>
			<px-checkbox value="Sam">Sam</px-checkbox>
			<px-checkbox value="Shane">Shane</px-checkbox>
		</px-checkbox-group>
		<h4>Disabled</h4>
		<px-checkbox-group :default-value="['Alex']" disabled>
			<px-checkbox value="Alex">Alex</px-checkbox>
			<px-checkbox value="Clint">Clint</px-checkbox>
		</px-checkbox-group>
	</px-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const group = ref<string[]>([])
</script>

Indeterminate State

Setting Checkbox's indeterminate to true can put the checkbox in an indeterminate state. This property only controls the styling and is independent of the current checkbox value.

Normal

Retro

Select All

Blue Jazz

Carrot

Coffee Bean

Parsnip

<template>
	<px-switch v-model="retro" active-label="Retro" inactive-label="Normal"></px-switch>
	<br />
	<br />
	<px-checkbox
		:variant="retro ? 'retro' : 'normal'"
		v-model="all"
		@change="selectAllChangeHandler"
		:indeterminate="group.length > 0 && group.length < options.length"
		>Select All</px-checkbox
	>
	<br />
	<br />
	<px-checkbox-group
		v-model="group"
		@change="groupChangeHandler"
		:variant="retro ? 'retro' : 'normal'"
	>
		<px-checkbox v-for="option in options" :key="option" :value="option">
			{{ option }}
		</px-checkbox>
	</px-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const group = ref<string[]>([])
const all = ref(false)

const options = ['Blue Jazz', 'Carrot', 'Coffee Bean', 'Parsnip']

const selectAllChangeHandler = (value: boolean) => {
	if (value) {
		group.value = [...options]
	} else {
		group.value = []
	}
}

const groupChangeHandler = (value: string[]) => {
	if (value.length === options.length) {
		all.value = true
	} else {
		all.value = false
	}
}

const retro = ref(false)
</script>

Vertical Arrangement

The direction property of CheckboxGroup is used to set the arrangement direction of child checkboxes.

Horizontal

Vertical

Normal

Retro

Anchovy

Tuna

Sardine

Bream

<template>
	<px-space>
		<px-switch
			v-model="vertical"
			active-label="Vertical"
			inactive-label="Horizontal"
		></px-switch>
		<px-switch v-model="retro" active-label="Retro" inactive-label="Normal"></px-switch>
	</px-space>
	<br />
	<br />
	<px-checkbox-group
		:direction="vertical ? 'vertical' : 'horizontal'"
		:variant="retro ? 'retro' : 'normal'"
	>
		<px-checkbox value="Anchovy">Anchovy</px-checkbox>
		<px-checkbox value="Tuna">Tuna</px-checkbox>
		<px-checkbox value="Sardine">Sardine</px-checkbox>
		<px-checkbox value="Bream">Bream</px-checkbox>
	</px-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const vertical = ref(false)
const retro = ref(false)
</script>

Checkbox Sizes

Both Checkbox and CheckboxGroup have a size property that can be used to set the size of checkbox.

Single Checkbox

Small

Medium

Large

Small & Retro

Medium & Retro

Large & Retro

Group

A

B

C

D

A

B

C

D

A

B

C

D

<template>
	<px-space direction="vertical">
		<h4>Single Checkbox</h4>
		<px-space>
			<px-checkbox size="small">Small</px-checkbox>
			<px-checkbox>Medium</px-checkbox>
			<px-checkbox size="large">Large</px-checkbox>
		</px-space>
		<px-space>
			<px-checkbox variant="retro" size="small">Small & Retro</px-checkbox>
			<px-checkbox variant="retro">Medium & Retro</px-checkbox>
			<px-checkbox variant="retro" size="large">Large & Retro</px-checkbox>
		</px-space>
		<h4>Group</h4>
		<px-checkbox-group :options="options" size="small"></px-checkbox-group>
		<px-checkbox-group :options="options"></px-checkbox-group>
		<px-checkbox-group :options="options" size="large"></px-checkbox-group>
	</px-space>
</template>

<script setup lang="ts">
const options = ['A', 'B', 'C', 'D']
</script>

Options Property

The options property of CheckboxGroup is used to directly pass in options, enabling quick creation of simple checkbox groups.

Normal

Retro

Lava Eel

Ice Pip

Midnight Carp

Slimejack

<template>
	<px-switch v-model="retro" active-label="Retro" inactive-label="Normal"></px-switch>
	<br />
	<br />
	<px-checkbox-group :options="options" :variant="retro ? 'retro' : 'normal'">
	</px-checkbox-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const options = [
	'Lava Eel',
	'Ice Pip',
	{
		value: 'Midnight Carp',
		label: 'Midnight Carp',
		disabled: true
	},
	'Slimejack'
]

const retro = ref(false)
</script>

API

CheckboxProps

Attribute	Type	Optional	Default	Description	Version
modelValue	boolean | null	True		The value of the Checkbox component (controlled mode).	0.0.3
defaultValue	boolean | null	True		The default value of the Checkbox component (uncontrolled mode).	0.0.3
indeterminate	boolean	True	false	Indeterminate state.	0.0.3
disabled	boolean	True	false	Disabled state.	0.0.3
readonly	boolean	True	false	Read-only state.	0.0.3
variant	'normal' | 'retro'	True	'normal'	The style variant of the checkbox.	0.0.3
label	string	True		The text of the checkbox.	0.0.3
value	any	True		the native value attribute of checkboxes.	0.0.3
size	'medium' | 'large' | 'small'	True	'medium'	Size of the checkbox.	0.0.3

CheckboxEvents

Event	Parameter	Description	Version
update:modelValue	value: boolean	Callback for updating modelValue.	0.0.3
input	value: boolean, event: InputEvent	Callback for selecting/deselecting the checkbox.	0.0.3
change	value: boolean, event: Event	Callback for when the checkbox selection state changes.	0.0.3
focus	event: FocusEvent	Callback for when the checkbox is focused.	0.0.3
blur	event: FocusEvent	Callback for when the checkbox loses focus.	0.0.3

CheckboxSlots

Slot	Parameter	Description	Version
default		The text of the checkbox.	0.0.3

CheckboxGroupProps

Attribute	Type	Optional	Default	Description	Version
modelValue	any[] | null	True		The value of the CheckboxGroup component (controlled mode).	0.0.3
defaultValue	any[] | null	True		The default value of the CheckboxGroup component (uncontrolled mode).	0.0.3
disabled	boolean	True	false	Disabled state.	0.0.3
readonly	boolean	True	false	Read-only state.	0.0.3
variant	'normal' | 'retro'	True		The style variant for descendant Radio components, which takes precedence over the variant of individual Radio components if set.	0.0.3
direction	'horizontal' | 'vertical'	True	'horizontal'	The arrangement direction of child checkbox components.	0.0.3
options	(CheckboxGroupOption | string)[]	True		Options for the checkbox group.	0.0.3
size	'medium' | 'large' | 'small'	True	'medium'	Size for descendant checkbox components. When set, it overrides the size prop on those components.	0.0.3

CheckboxGroupEvents

Event	Parameter	Description	Version
update:modelValue	value: any[]	Callback for updating modelValue.	0.0.3
change	value: any[]	Callback for when the checkbox group selection changes.	0.0.3

CheckboxGroupSlots

Slot	Parameter	Description	Version
default		Child checkbox components.	0.0.3

CheckboxGroupOption

export interface Option<T = any> {
	value: T
	label: string
}

export interface CheckboxGroupOption<T = any> extends Option<T> {
	disabled?: boolean
	key?: string | number | symbol
}