Checkbox Component

Component Status

| Component | Status | | ------------- | ----------------------------------------------------------- | | Checkbox | | | CheckboxGroup | |

Multi-select checkbox components for Phila UI. Use Checkbox for a standalone checkbox, or CheckboxGroup to manage a set of related options with a shared label, description, and error state.

Installation

pnpm add @phila/phila-ui-checkbox @phila/phila-ui-core
# or
npm install @phila/phila-ui-checkbox @phila/phila-ui-core

Import core styles in your main entry file (e.g., main.js|ts):

import "@phila/phila-ui-core/styles/template-light.css";

Usage

CheckboxGroup (recommended)

CheckboxGroup's modelValue is a map of choice value → checked, not an array — every choice gets a key, so the shape is stable regardless of which options have been touched:

<script setup lang="ts">
import { CheckboxGroup } from "@phila/phila-ui-checkbox";
import { ref } from "vue";

const modelValue = ref<Record<string, boolean>>({});
const choices = [
  { text: "Option A", value: "a" },
  { text: "Option B", value: "b" },
  { text: "Option C", value: "c", tooltip: "Extra context about Option C shown on hover." },
];
</script>

<template>
  <CheckboxGroup
    groupLabel="Choose all that apply"
    description="Select one or more options."
    :choices="choices"
    v-model="modelValue"
  />
</template>

Checkbox (standalone — boolean)

<script setup lang="ts">
import { Checkbox } from "@phila/phila-ui-checkbox";
import { ref } from "vue";

const agreed = ref(false);
</script>

<template>
  <Checkbox text="I agree to the terms" v-model="agreed" />
</template>

Checkbox (standalone — array)

When multiple checkboxes share the same array, each one adds or removes its value from the array:

<script setup lang="ts">
import { Checkbox } from "@phila/phila-ui-checkbox";
import { ref } from "vue";

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

<template>
  <Checkbox text="Option A" value="a" v-model="selected" />
  <Checkbox text="Option B" value="b" v-model="selected" />
</template>

Indeterminate and tooltip

<Checkbox text="Select all" :indeterminate="true" v-model="someSelected" />
<Checkbox text="Option with help" tooltip="Extra context shown on hover." v-model="agreed" />

Checkbox Props

| Prop | Type | Default | Description | | --------------- | ----------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------- | | text | string | — | Label text displayed next to the checkbox | | modelValue | boolean \| Array<string \| number \| boolean> | — | Bound value. Pass a boolean for a single checkbox; pass an array when multiple checkboxes share state | | value | string \| number \| boolean | — | The value added to / removed from the array when using array mode | | name | string | — | HTML name attribute | | disabled | boolean | false | Disables the checkbox | | error | boolean | false | Applies error styling | | indeterminate | boolean | false | Renders the native indeterminate visual state (e.g. a "select all" checkbox with a partial selection) | | tooltip | string | — | Shows an info icon next to the label that reveals this text on hover | | className | string | — | Additional CSS classes |

CheckboxGroup Props

| Prop | Type | Default | Description | | -------------- | -------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | groupLabel | string | — | Label displayed above the group | | description | string | — | Optional helper text below the label | | choices | { text: string, value: string \| number \| boolean, tooltip?: string }[] | — | Array of options to render | | modelValue | Record<string, boolean> | — | Map of choice value (stringified) → checked (use with v-model) | | error | boolean | false | Applies error styling to the group | | errorMessage | string | — | Error message shown below the options when error is true | | disabled | boolean | false | Disables all checkboxes in the group | | className | string | — | Additional CSS classes |

Events

Checkbox

| Event | Payload | Description | | ------------------- | ----------------------------------------------- | ---------------------------------------- | | update:modelValue | boolean \| Array<string \| number \| boolean> | Emitted when the checkbox is toggled | | change | Event | Native change event | | focus | FocusEvent | Emitted when the checkbox receives focus | | blur | FocusEvent | Emitted when the checkbox loses focus |

CheckboxGroup

| Event | Payload | Description | | ------------------- | ------------------------- | ---------------------------------------------------------------- | | update:modelValue | Record<string, boolean> | Emitted with the full updated map whenever any choice is toggled |

Visual States

| State | Description | | ------------------ | ---------------------------------------------- | | Default | Gray border, white background | | Hover | Primary-colored border (2px) | | Checked | Primary fill with white checkmark | | Focus | Primary-colored outline (2px) around the label | | Error | Error-colored border (2px) | | Disabled | Muted border and text, not interactive | | Disabled + Checked | Muted fill with white checkmark |

Development

Install Dependencies

pnpm install

Run Demo

pnpm dev

Run lint

pnpm lint

Create Production Build

pnpm build

Publishing to NPM

Follow the release instructions using changesets.

License

MIT