# Checkbox

Custom-styled checkbox with bindable checked. Default and primary variants.

- Package: `@mielui/svelte`
- Component version: `1.0.0`
- Depends on Mielui components: _internal/utils
- Shared utilities: components/_internal/field-metadata, hugeicons-icon, utils.cn

## Install

~~~~sh
pnpm dlx @mielui/svelte add checkbox
~~~~

## API

This reference is generated at build time from the component manifest, public `index.ts`, and documentation examples below. Changes to those source files are reflected here in the published Markdown. Standard Svelte and HTML attributes accepted by the exported prop types are supported.


### Checkbox

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| checked | boolean \| undefined | false | No | Yes | Whether it is checked. Bind it to control the state from outside. |
| label | string \| undefined | - | No | No | Visible label linked to the control. |
| description | string \| undefined | - | No | No | Supporting text under the label, announced with the control. |
| disabled | boolean \| undefined | - | No | No | Prevents interaction and dims the control. |
| variant | "default" \| "card" \| undefined | 'default' | No | No | `card` frames the box and its text as a bordered row. |
| size | "sm" \| "md" \| "lg" \| undefined | 'md' | No | No | Size of the box. |
| onCheckedChange | ((checked: boolean) => void) \| undefined | - | No | No | Called with the new state when it changes. |
| class | (string & (ClassValue \| null)) \| undefined | - | No | No | Classes added to the element. |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Public types

~~~~ts
import type { DefaultProps } from '@mielui/svelte/utils';
import type { HTMLInputAttributes } from 'svelte/elements';
import Checkbox from './checkbox.svelte';

export type CheckboxProps = {
    /** Whether it is checked. Bind it to control the state from outside. */
    checked?: boolean;
    /** Visible label linked to the control. */
    label?: string;
    /** Supporting text under the label, announced with the control. */
    description?: string;
    /** Prevents interaction and dims the control. */
    disabled?: boolean;
    /** `card` frames the box and its text as a bordered row. */
    variant?: 'default' | 'card';
    /** Size of the box. */
    size?: 'sm' | 'md' | 'lg';
    /** Called with the new state when it changes. */
    onCheckedChange?: (checked: boolean) => void;
} & DefaultProps &
    Omit<HTMLInputAttributes, 'children' | 'type' | 'checked' | 'size'>;

export { Checkbox };
export default Checkbox;
~~~~

## Examples

### Checked

~~~~svelte
<script lang="ts">
    import { Checkbox } from '@mielui/svelte/components/checkbox';
</script>

<div class="flex items-center justify-center">
    <Checkbox label="Checked by default" checked />
</div>
~~~~

### Disabled

~~~~svelte
<script lang="ts">
    import { Checkbox } from '@mielui/svelte/components/checkbox';
</script>

<div class="flex items-center justify-center">
    <Checkbox label="Disabled option" disabled />
</div>
~~~~

### Events

~~~~svelte
<script lang="ts">
    import { Checkbox } from '@mielui/svelte/components/checkbox';

    let log = $state('Not accepted yet');
</script>

<div class="flex flex-col gap-3">
    <Checkbox
        label="I accept the terms"
        variant="card"
        onCheckedChange={(checked) => {
            log = checked ? 'Accepted' : 'Not accepted yet';
        }}
    />
    <p role="status" class="text-sm text-foreground-muted">{log}</p>
</div>
~~~~

### Hero

~~~~svelte
<script lang="ts">
    import { numberShuffle } from '@mielui/svelte/actions/number-shuffle';
    import { Checkbox } from '@mielui/svelte/components/checkbox';

    let finalizePricing = $state(true);
    let writeChangelog = $state(true);
    let qaNavigation = $state(false);
    let scheduleAnnouncement = $state(false);
    let updateDocs = $state(false);

    const completedCount = $derived(
        [finalizePricing, writeChangelog, qaNavigation, scheduleAnnouncement, updateDocs].filter(
            Boolean
        ).length
    );
    const totalCount = 5;
</script>

<div class="w-full max-w-80">
    <div class="mb-4 flex items-center justify-between gap-4">
        <h3 class="text-foreground [font-weight:var(--font-weight-label,500)]">Launch checklist</h3>
        <span
            class="flex gap-1 text-sm tabular-nums text-foreground-muted [font-weight:var(--font-weight-label,500)]"
        >
            <span use:numberShuffle={{ value: completedCount }}>{completedCount}</span>
            <span>of {totalCount}</span>
        </span>
    </div>

    <div class="space-y-3">
        <Checkbox bind:checked={finalizePricing} label="Finalize pricing page" />
        <Checkbox bind:checked={writeChangelog} label="Write the changelog" />
        <Checkbox bind:checked={qaNavigation} label="QA mobile navigation" />
        <Checkbox bind:checked={scheduleAnnouncement} label="Schedule the announcement tweet" />
        <Checkbox bind:checked={updateDocs} label="Update docs screenshots" />
    </div>
</div>
~~~~

### Label Only

~~~~svelte
<script lang="ts">
    import { Checkbox } from '@mielui/svelte/components/checkbox';
</script>

<div class="flex items-center justify-center">
    <Checkbox label="Receive updates" />
</div>
~~~~

### Sizes

~~~~svelte
<script lang="ts">
    import { Checkbox } from '@mielui/svelte/components/checkbox';
</script>

<div class="flex flex-wrap items-center gap-6">
    <Checkbox size="sm" label="Small · 14px" />
    <Checkbox size="md" label="Medium · 18px" checked />
    <Checkbox size="lg" label="Large · 22px" checked />
</div>
~~~~

### With Description

~~~~svelte
<script lang="ts">
    import { Checkbox } from '@mielui/svelte/components/checkbox';
</script>

<div class="flex items-center justify-center">
    <Checkbox label="Receive product updates" description="Roughly one email per month" />
</div>
~~~~

For the rendered reference, visit [/docs/components/checkbox](/docs/components/checkbox).