Skip to content

Checkbox

Checkbox with label and indeterminate state. Accessible via keyboard (Space/Enter) with support for form integration.

import { Checkbox } from "phoundry-ui";

Basic toggle

Loading interactive example…

View source
basic-toggle.svelte
<script lang="ts">
import { Checkbox } from "phoundry-ui";
let basic = $state(false);
</script>
<div class="flex items-center gap-3">
<Checkbox checked={basic} onchange={() => (basic = !basic)} />
<span class="text-xs text-txt-tertiary"
>{basic ? "Checked" : "Unchecked"}</span
>
</div>

With label and description

Loading interactive example…

View source
with-label-and-description.svelte
<script lang="ts">
import { Checkbox } from "phoundry-ui";
let withLabel = $state(false);
let withDesc = $state(true);
let agree = $state(false);
</script>
<div class="flex flex-col gap-3">
<Checkbox
checked={withLabel}
onchange={() => (withLabel = !withLabel)}
label="Enable notifications"
/>
<Checkbox
checked={withDesc}
onchange={() => (withDesc = !withDesc)}
label="Accept terms and conditions"
description="You agree to our privacy policy"
/>
</div>

Indeterminate state

Loading interactive example…

View source
indeterminate-state.svelte
<script lang="ts">
import { Checkbox } from "phoundry-ui";
let indeterminate = $state(true);
</script>
<Checkbox
checked={false}
{indeterminate}
onchange={() => {
indeterminate = false;
}}
label="Select all"
description="Some items are selected"
/>

Sizes

Loading interactive example…

View source
sizes.svelte
<script lang="ts">
import { Checkbox } from "phoundry-ui";
let mdSize = $state(true);
</script>
<div class="flex flex-col gap-3">
<Checkbox
checked={mdSize}
onchange={() => (mdSize = !mdSize)}
size="sm"
label="Small box"
/>
<Checkbox
checked={mdSize}
onchange={() => (mdSize = !mdSize)}
size="md"
label="Medium box"
/>
</div>

Form name (hidden input)

Loading interactive example…

View source
form-name-hidden-input.svelte
<script lang="ts">
import { Checkbox } from "phoundry-ui";
let agree = $state(false);
</script>
<p class="mb-2 text-xs text-txt-secondary">
With <code>name</code>, a hidden <code>&lt;input type="checkbox"&gt;</code>
mirrors state for native submission. Keep <code>id</code> in sync with external
labels if you do not use the built-in label.
</p>
<Checkbox
checked={agree}
onchange={() => (agree = !agree)}
name="demo-terms"
label="Demo field name"
/>

Disabled

Loading interactive example…

View source
disabled.svelte
<script lang="ts">
import { Checkbox } from "phoundry-ui";
let disabledChecked = $state(true);
</script>
<div class="flex flex-col gap-3">
<Checkbox checked={disabledChecked} disabled label="Disabled (checked)" />
<Checkbox checked={false} disabled label="Disabled (unchecked)" />
</div>

API

From phoundry-ui@0.4.21

NameTypeDefaultDescription
checkedrequiredboolean—Whether the checkbox is checked
onchange() => void—Called when the checkbox is toggled
indeterminatebooleanfalseShows a dash icon instead of a checkmark (mixed state)
disabledbooleanfalsePrevents interaction
size"sm" | "md"'sm'Indicator box (~14px sm / ~16px md display size, not full control height)
labelstring | Snippet<[]>—Inline label rendered next to the checkbox
descriptionstring—Helper text below the label
classClassValue—Additional CSS classes
stylestring—Inline styles on the component styling target described below.
idstring—Element id (auto-generated if omitted)
namestring—Form field name - renders a hidden input
elementbindableHTMLButtonElement—Bindable reference to the checkbox button.

Other native attributes: Additional attributes forwarded to the checkbox <button> (e.g. aria-invalid, data-testid).

Usage tips

  • Use indeterminate for “select all” patterns where only some children are checked.
  • Pass a name prop to render a hidden <input> for native form submission.
  • When using without the label prop, supply aria-label or aria-labelledby on the control.

Styling

.ph-checkbox is the stable root identification hook. Styling is component-local vanilla CSS; data-size always identifies the selected size. The root is the label wrapper when labelled and the control button otherwise. class and style apply to that root; native attributes, attachments, and bind:element still target the button. Indicator sizes use --ph-indicator-sm (0.875rem) and --ph-indicator-md (1rem), with --ph-comp-icon-xs / --ph-comp-icon-sm for icons. Customize the shared icon shadow with --ph-indicator-icon-filter and the surface shadow with --ph-input-shadow. Internal part selectors and --_ph-* properties are implementation details. Filled indicators use the active Theme’s --text-on-accent foreground.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.