Checkbox

An easily stylable checkbox component.

Enable notifications

<script lang="ts">
	import { Checkbox } from '@sveltery/base/checkbox';
</script>

<label class="flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white">
	<Checkbox.Root
		defaultChecked
		class="flex size-4 shrink-0 items-center justify-center border rounded-none p-0 border-neutral-950 bg-white text-white dark:border-white dark:bg-neutral-950 dark:text-neutral-950 data-checked:bg-neutral-950 data-checked:text-white dark:data-checked:bg-white dark:data-checked:text-neutral-950 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
	>
		<Checkbox.Indicator class="flex data-unchecked:hidden">
			<svg
				width="16"
				height="16"
				viewBox="0 0 16 16"
				fill="none"
				stroke="currentColor"
				style="display: block"
			>
				<path d="m2.5 8.5 4 4 7-9" />
			</svg>
		</Checkbox.Indicator>
	</Checkbox.Root>
	Enable notifications
</label>

Usage guidelines

Form controls must have an accessible name: It can be created using a <label> element or the Field component. See Labeling a checkbox and the forms guide.

Anatomy

Import the component and assemble its parts:

<script lang="ts">
	import { Checkbox } from '@sveltery/base/checkbox';
</script>

<Checkbox.Root>
	<Checkbox.Indicator />
</Checkbox.Root>

Examples

Labeling a checkbox

An enclosing <label> is the simplest labeling pattern:

<label>
	<Checkbox.Root />
	Accept terms and conditions
</label>

By default, <Checkbox.Root> renders a <span> element to support enclosing labels. Prefer rendering the checkbox as a native button when using sibling labels (for/id). Set nativeButton and render a <button> with the render snippet.

<div>
	<label for="notifications-checkbox">Enable notifications</label>
	<Checkbox.Root id="notifications-checkbox" nativeButton>
		{#snippet render(props, _state, children)}
			<button type="button" {...props}>{@render children?.()}</button>
		{/snippet}
		<Checkbox.Indicator />
	</Checkbox.Root>
</div>

Native buttons with wrapping labels are supported by using the render snippet to avoid invalid HTML, so the hidden input is placed outside the label:

<Checkbox.Root nativeButton>
	{#snippet render(props, _state, children)}
		<label>
			<button type="button" {...props}>{@render children?.()}</button>
			Enable notifications
		</label>
	{/snippet}
</Checkbox.Root>

Form integration

Use Field to handle label associations and form integration:

<Form>
	<Field.Root name="stayLoggedIn">
		<Field.Label>
			<Checkbox.Root />
			Stay logged in for 7 days
		</Field.Label>
	</Field.Root>
</Form>

API reference

Root

Represents the checkbox itself. Renders a <span> and a hidden checkbox beside it.

checked boolean false

Name: checked
Description: Whether the checkbox is currently ticked. Use bind:checked to share it with the parent. Inside a group, the group value wins.
Type: boolean
Default: false
Binding: bind:checked

defaultChecked boolean false

Name: defaultChecked
Description: The state an empty checked starts from, as on an HTML checkbox.
Type: boolean
Default: false

disabled boolean | null false

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | null
Default: false

readonly boolean | null false

Name: readonly
Description: Whether the user should be unable to tick or untick the checkbox.
Type: boolean | null
Default: false

required boolean | null false

Name: required
Description: Whether the user must tick the checkbox before submitting a form.
Type: boolean | null
Default: false

indeterminate boolean false

Name: indeterminate
Description: Whether the checkbox is in a mixed state: neither ticked nor unticked.
Type: boolean
Default: false

parent boolean false

Name: parent
Description: Whether this checkbox controls every value in a parent CheckboxGroup. It sets data-parent and is left out of form submission.
Type: boolean
Default: false

nativeButton boolean false

Name: nativeButton
Description: Whether the host is a native <button>. Set true and render a <button>. The id is then applied to that button instead of the hidden input.
Type: boolean
Default: false

name string | null —

Name: name
Description: Identifies the field when a form is submitted.
Type: string | null

value string —

Name: value
Description: The value submitted with the form when the checkbox is ticked. By default, the checkbox submits "on", matching a native checkbox.
Type: string

uncheckedValue string —

Name: uncheckedValue
Description: The value submitted with the form when the checkbox is unticked. By default, an unticked checkbox does not submit a value.
Type: string

form string | null —

Name: form
Description: Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
Type: string | null

id string | null —

Name: id
Description: The id of the hidden input. When nativeButton is true, the id is applied to the root element instead.
Type: string | null

onCheckedChange function —

Name: onCheckedChange
Description: Called before the checked state changes. Call eventDetails.cancel() to veto it.
Type: (checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => void

onclick MouseEventHandler<HTMLElement> | null —

Name: onclick
Description: Runs before the checkbox's click handler. Call event.preventDefault() to skip it.
Type: MouseEventHandler<HTMLElement> | null

render Snippet<[props: CheckboxHostProps, state: CheckboxRootState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <span>. Spread props onto the host element.
Type: Snippet<[props: CheckboxHostProps, state: CheckboxRootState, children: Snippet | undefined]>

checked boolean

Name: checked
Description: Whether the checkbox is currently ticked.
Type: boolean

disabled boolean

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean

readOnly boolean

Name: readOnly
Description: Whether the user should be unable to tick or untick the checkbox.
Type: boolean

required boolean

Name: required
Description: Whether the user must tick the checkbox before submitting a form.
Type: boolean

indeterminate boolean

Name: indeterminate
Description: Whether the checkbox is in a mixed state. While mixed, aria-checked is mixed and the checked style hooks are omitted.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-checked

Present when the checkbox is checked.

data-unchecked

Present when the checkbox is not checked.

data-disabled

Present when the checkbox is disabled.

data-readonly

Present when the checkbox is readonly.

data-required

Present when the checkbox is required.

data-valid

Present when the checkbox is in a valid state (when wrapped in Field.Root).

data-invalid

Present when the checkbox is in an invalid state (when wrapped in Field.Root).

data-dirty

Present when the checkbox's value has changed (when wrapped in Field.Root).

data-touched

Present when the checkbox has been touched (when wrapped in Field.Root).

data-filled

Present when the checkbox is checked (when wrapped in Field.Root).

data-focused

Present when the checkbox is focused (when wrapped in Field.Root).

data-indeterminate

Present when the checkbox is in an indeterminate state.

data-parent

Present when the checkbox is a parent checkbox.

Attribute	Description	-
`data-checked`	Present when the checkbox is checked.
`data-unchecked`	Present when the checkbox is not checked.
`data-disabled`	Present when the checkbox is disabled.
`data-readonly`	Present when the checkbox is readonly.
`data-required`	Present when the checkbox is required.
`data-valid`	Present when the checkbox is in a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the checkbox is in an invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the checkbox's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the checkbox has been touched (when wrapped in Field.Root).
`data-filled`	Present when the checkbox is checked (when wrapped in Field.Root).
`data-focused`	Present when the checkbox is focused (when wrapped in Field.Root).
`data-indeterminate`	Present when the checkbox is in an indeterminate state.
`data-parent`	Present when the checkbox is a parent checkbox.

Indicator

Indicates whether the checkbox is ticked. Renders a <span> while ticked, mixed, or kept mounted.

keepMounted boolean false

Name: keepMounted
Description: Whether to keep the indicator in the DOM when the checkbox is unticked and not mixed.
Type: boolean
Default: false

render Snippet<[props: HTMLAttributes<HTMLSpanElement>, state: CheckboxIndicatorState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <span>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLSpanElement>, state: CheckboxIndicatorState, children: Snippet | undefined]>

transitionStatus CheckboxIndicatorPhase

Name: transitionStatus
Description: Indicator motion phase.
Type: CheckboxIndicatorPhase