# Checkbox

Native checkbox with an optional label and description, custom styled without JavaScript.

- Category: Form
- Status: stable
- Registry: https://markas.jenderalcorp.com/r/checkbox.json
- CLI: `npx markasui@latest add checkbox`

## When to use

Consent or a yes/no choice that only applies after the form is submitted, or several independent options.

- Use Switch for settings that apply immediately
- Always set a label or aria-label

## Code

### Blade

Save at `resources/views/components/markas/checkbox.blade.php`. No extra dependencies.

```blade
@props([
    'label' => null,
    'description' => null,
])

@php
    $root = 'flex items-start gap-3 has-disabled:cursor-not-allowed has-disabled:opacity-50';
    $control = 'relative mt-0.5 flex size-4 shrink-0';
    $box = 'peer size-4 shrink-0 cursor-pointer appearance-none rounded-sm border border-faint bg-surface transition-colors duration-150 ease-out checked:border-primary checked:bg-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed aria-invalid:border-danger motion-reduce:transition-none';
    $icon = 'pointer-events-none absolute inset-0 size-4 text-on-primary opacity-0 peer-checked:opacity-100';
    $text = 'grid gap-0.5';
    $labelClass = 'text-sm font-medium text-ink';
    $descriptionClass = 'text-sm text-muted';

    // Same id on every render, so Livewire's morph (which matches elements by id) keeps the element. Pass `id` to set it.
    $idKey = 'markas-checkbox|'.(isset($this) && $this instanceof \Livewire\Component ? $this->getId() : '').'|'.($attributes->get('wire:key') ?? $attributes->whereStartsWith('wire:model')->first() ?? $attributes->get('name')).'|'.$attributes->get('value').'|';
    for ($idIndex = 0; $__env->hasRenderedOnce($idKey.$idIndex); $idIndex++);
    $__env->markAsRenderedOnce($idKey.$idIndex);
    $id = $attributes->get('id') ?? 'markas-checkbox-'.hash('xxh32', $idKey.$idIndex);
    $describedBy = $description ? $id.'-description' : null;
@endphp

<div class="{{ $root }}">
    <span class="{{ $control }}">
        <input type="checkbox" {{ $attributes->merge(['id' => $id, 'aria-describedby' => $describedBy])->class([$box]) }} />
        <svg class="{{ $icon }}" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m4 8.5 2.5 2.5L12 5.5" /></svg>
    </span>
    @if ($label || $description)
        <div class="{{ $text }}">
            @if ($label)
                <label for="{{ $id }}" class="{{ $labelClass }}">{{ $label }}</label>
            @endif
            @if ($description)
                <p id="{{ $id }}-description" class="{{ $descriptionClass }}">{{ $description }}</p>
            @endif
        </div>
    @endif
</div>
```

```blade
<x-markas.checkbox name="terms" label="I agree to the terms of service" required />
<x-markas.checkbox name="updates" label="Send me product updates" description="At most one email per month." :checked="old('updates')" />
```

### React

Save at `src/components/markas/Checkbox.tsx`. No extra dependencies.

```tsx
import { useId, type ComponentProps, type ReactNode } from "react";

const root =
  "flex items-start gap-3 has-disabled:cursor-not-allowed has-disabled:opacity-50";
const control = "relative mt-0.5 flex size-4 shrink-0";
const box =
  "peer size-4 shrink-0 cursor-pointer appearance-none rounded-sm border border-faint bg-surface transition-colors duration-150 ease-out checked:border-primary checked:bg-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed aria-invalid:border-danger motion-reduce:transition-none";
const icon =
  "pointer-events-none absolute inset-0 size-4 text-on-primary opacity-0 peer-checked:opacity-100";
const text = "grid gap-0.5";
const labelClass = "text-sm font-medium text-ink";
const descriptionClass = "text-sm text-muted";
const cx = (...c: (string | false | null | undefined)[]) =>
  c.filter(Boolean).join(" ");

export type CheckboxProps = Omit<ComponentProps<"input">, "type"> & {
  label?: ReactNode;
  description?: ReactNode;
};

export function Checkbox({
  label,
  description,
  id,
  className,
  ...props
}: CheckboxProps) {
  const generatedId = useId();
  const checkboxId = id ?? generatedId;

  return (
    <div className={root}>
      <span className={control}>
        <input
          id={checkboxId}
          aria-describedby={
            description ? `${checkboxId}-description` : undefined
          }
          className={cx(box, className)}
          {...props}
          type="checkbox"
        />
        <svg
          className={icon}
          viewBox="0 0 16 16"
          fill="none"
          stroke="currentColor"
          strokeWidth="2"
          strokeLinecap="round"
          strokeLinejoin="round"
          aria-hidden="true"
        >
          <path d="m4 8.5 2.5 2.5L12 5.5" />
        </svg>
      </span>
      {(label || description) && (
        <div className={text}>
          {label && (
            <label htmlFor={checkboxId} className={labelClass}>
              {label}
            </label>
          )}
          {description && (
            <p id={`${checkboxId}-description`} className={descriptionClass}>
              {description}
            </p>
          )}
        </div>
      )}
    </div>
  );
}
```

```tsx
import { Checkbox } from "@/components/markas/Checkbox";

<Checkbox name="terms" label="I agree to the terms of service" required />
<Checkbox
  name="updates"
  label="Send me product updates"
  description="At most one email per month."
  defaultChecked
/>
```

### Vue

Save at `src/components/markas/Checkbox.vue`. No extra dependencies.

```vue
<script setup lang="ts">
import { computed, useId } from "vue";

defineOptions({ inheritAttrs: false });

const props = defineProps<{
  label?: string;
  description?: string;
  id?: string;
}>();
const model = defineModel<boolean>({ default: false });

const root =
  "flex items-start gap-3 has-disabled:cursor-not-allowed has-disabled:opacity-50";
const control = "relative mt-0.5 flex size-4 shrink-0";
const box =
  "peer size-4 shrink-0 cursor-pointer appearance-none rounded-sm border border-faint bg-surface transition-colors duration-150 ease-out checked:border-primary checked:bg-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed aria-invalid:border-danger motion-reduce:transition-none";
const icon =
  "pointer-events-none absolute inset-0 size-4 text-on-primary opacity-0 peer-checked:opacity-100";
const text = "grid gap-0.5";
const labelClass = "text-sm font-medium text-ink";
const descriptionClass = "text-sm text-muted";

const generatedId = useId();
const checkboxId = computed(() => props.id ?? generatedId);
</script>

<template>
  <div :class="root">
    <span :class="control">
      <input
        :id="checkboxId"
        v-model="model"
        :aria-describedby="
          props.description ? `${checkboxId}-description` : undefined
        "
        :class="box"
        v-bind="$attrs"
        type="checkbox"
      />
      <svg
        :class="icon"
        viewBox="0 0 16 16"
        fill="none"
        stroke="currentColor"
        stroke-width="2"
        stroke-linecap="round"
        stroke-linejoin="round"
        aria-hidden="true"
      >
        <path d="m4 8.5 2.5 2.5L12 5.5" />
      </svg>
    </span>
    <div v-if="props.label || props.description" :class="text">
      <label v-if="props.label" :for="checkboxId" :class="labelClass">{{
        props.label
      }}</label>
      <p
        v-if="props.description"
        :id="`${checkboxId}-description`"
        :class="descriptionClass"
      >
        {{ props.description }}
      </p>
    </div>
  </div>
</template>
```

```vue
<script setup lang="ts">
import { ref } from "vue";
import Checkbox from "@/components/markas/Checkbox.vue";

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

<template>
  <Checkbox
    v-model="updates"
    name="updates"
    label="Send me product updates"
    description="At most one email per month."
  />
</template>
```

### Svelte

Save at `src/lib/components/markas/Checkbox.svelte`. No extra dependencies.

```svelte
<script lang="ts">
  import type { HTMLInputAttributes } from "svelte/elements";

  const root =
    "flex items-start gap-3 has-disabled:cursor-not-allowed has-disabled:opacity-50";
  const control = "relative mt-0.5 flex size-4 shrink-0";
  const box =
    "peer size-4 shrink-0 cursor-pointer appearance-none rounded-sm border border-faint bg-surface transition-colors duration-150 ease-out checked:border-primary checked:bg-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed aria-invalid:border-danger motion-reduce:transition-none";
  const icon =
    "pointer-events-none absolute inset-0 size-4 text-on-primary opacity-0 peer-checked:opacity-100";
  const text = "grid gap-0.5";
  const labelClass = "text-sm font-medium text-ink";
  const descriptionClass = "text-sm text-muted";

  type Props = Omit<HTMLInputAttributes, "type"> & {
    label?: string;
    description?: string;
    checked?: boolean;
  };

  let {
    label,
    description,
    id,
    checked = $bindable(false),
    class: className,
    ...rest
  }: Props = $props();

  const generatedId = $props.id();
  const checkboxId = $derived(id ?? generatedId);
</script>

<div class={root}>
  <span class={control}>
    <input
      id={checkboxId}
      bind:checked
      aria-describedby={description ? `${checkboxId}-description` : undefined}
      class={[box, className]}
      {...rest}
      type="checkbox"
    />
    <svg
      class={icon}
      viewBox="0 0 16 16"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
      aria-hidden="true"
    >
      <path d="m4 8.5 2.5 2.5L12 5.5" />
    </svg>
  </span>
  {#if label || description}
    <div class={text}>
      {#if label}
        <label for={checkboxId} class={labelClass}>{label}</label>
      {/if}
      {#if description}
        <p id={`${checkboxId}-description`} class={descriptionClass}>
          {description}
        </p>
      {/if}
    </div>
  {/if}
</div>
```

```svelte
<script lang="ts">
  import Checkbox from "$lib/components/markas/Checkbox.svelte";

  let updates = $state(false);
</script>

<Checkbox
  bind:checked={updates}
  name="updates"
  label="Send me product updates"
  description="At most one email per month."
/>
```

### Astro

Save at `src/components/markas/Checkbox.astro`. No extra dependencies.

```astro
---
import type { HTMLAttributes } from "astro/types";

const root =
  "flex items-start gap-3 has-disabled:cursor-not-allowed has-disabled:opacity-50";
const control = "relative mt-0.5 flex size-4 shrink-0";
const box =
  "peer size-4 shrink-0 cursor-pointer appearance-none rounded-sm border border-faint bg-surface transition-colors duration-150 ease-out checked:border-primary checked:bg-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed aria-invalid:border-danger motion-reduce:transition-none";
const icon =
  "pointer-events-none absolute inset-0 size-4 text-on-primary opacity-0 peer-checked:opacity-100";
const text = "grid gap-0.5";
const labelClass = "text-sm font-medium text-ink";
const descriptionClass = "text-sm text-muted";

type Props = Omit<HTMLAttributes<"input">, "type"> & {
  label?: string;
  description?: string;
};

const { label, description, id, class: className, ...rest } = Astro.props;
const checkboxId = id ?? `markas-checkbox-${crypto.randomUUID().slice(0, 8)}`;
---

<div class={root}>
  <span class={control}>
    <input
      id={checkboxId}
      aria-describedby={description ? `${checkboxId}-description` : undefined}
      class:list={[box, className]}
      {...rest}
      type="checkbox"
    />
    <svg
      class={icon}
      viewBox="0 0 16 16"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
      aria-hidden="true"
    >
      <path d="m4 8.5 2.5 2.5L12 5.5"></path>
    </svg>
  </span>
  {
    (label || description) && (
      <div class={text}>
        {label && (
          <label for={checkboxId} class={labelClass}>
            {label}
          </label>
        )}
        {description && (
          <p id={`${checkboxId}-description`} class={descriptionClass}>
            {description}
          </p>
        )}
      </div>
    )
  }
</div>
```

```astro
---
import Checkbox from "@/components/markas/Checkbox.astro";
---

<Checkbox name="terms" label="I agree to the terms of service" required />
<Checkbox name="updates" label="Send me product updates" description="At most one email per month." checked />
```

No client script: the checkbox is a native input.

### Angular

Save at `src/app/markas/checkbox.component.ts`. No extra dependencies.

```ts
import {
  booleanAttribute,
  ChangeDetectionStrategy,
  Component,
  computed,
  input,
  linkedSignal,
  output,
} from "@angular/core";

const root =
  "flex items-start gap-3 has-disabled:cursor-not-allowed has-disabled:opacity-50";
const control = "relative mt-0.5 flex size-4 shrink-0";
const box =
  "peer size-4 shrink-0 cursor-pointer appearance-none rounded-sm border border-faint bg-surface transition-colors duration-150 ease-out checked:border-primary checked:bg-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed aria-invalid:border-danger motion-reduce:transition-none";
const icon =
  "pointer-events-none absolute inset-0 size-4 text-on-primary opacity-0 peer-checked:opacity-100";
const text = "grid gap-0.5";
const labelClass = "text-sm font-medium text-ink";
const descriptionClass = "text-sm text-muted";

let nextId = 0;

/**
 * Host stays out of layout (display: contents). id, name, value, aria-label, and class move
 * to the input, so the host attributes are cleared to avoid duplicate ids and labels.
 */
@Component({
  selector: "markas-checkbox",
  changeDetection: ChangeDetectionStrategy.OnPush,
  host: {
    class: "contents",
    "[attr.id]": "null",
    "[attr.name]": "null",
    "[attr.value]": "null",
    "[attr.aria-label]": "null",
  },
  template: `
    <div [class]="root">
      <span [class]="control">
        <input
          #field
          [id]="checkboxId()"
          [class]="boxClass()"
          [checked]="on()"
          [disabled]="disabled()"
          [required]="required()"
          [attr.name]="name() ?? null"
          [attr.value]="value() ?? null"
          [attr.aria-label]="ariaLabel() ?? null"
          [attr.aria-describedby]="
            description() ? checkboxId() + '-description' : null
          "
          type="checkbox"
          (change)="toggle(field.checked)"
        />
        <svg
          [class]="icon"
          viewBox="0 0 16 16"
          fill="none"
          stroke="currentColor"
          stroke-width="2"
          stroke-linecap="round"
          stroke-linejoin="round"
          aria-hidden="true"
        >
          <path d="m4 8.5 2.5 2.5L12 5.5" />
        </svg>
      </span>
      @if (label() || description()) {
        <div [class]="text">
          @if (label()) {
            <label [for]="checkboxId()" [class]="labelClass">{{
              label()
            }}</label>
          }
          @if (description()) {
            <p [id]="checkboxId() + '-description'" [class]="descriptionClass">
              {{ description() }}
            </p>
          }
        </div>
      }
    </div>
  `,
})
export class Checkbox {
  readonly label = input<string>();
  readonly description = input<string>();
  readonly id = input<string>();
  readonly name = input<string>();
  readonly value = input<string>();
  readonly checked = input(false, { transform: booleanAttribute });
  readonly disabled = input(false, { transform: booleanAttribute });
  readonly required = input(false, { transform: booleanAttribute });
  readonly ariaLabel = input<string | undefined>(undefined, {
    alias: "aria-label",
  });
  readonly userClass = input("", { alias: "class" });
  /** Emits the new state; together with `checked` this enables `[(checked)]`. */
  readonly checkedChange = output<boolean>();

  protected readonly root = root;
  protected readonly control = control;
  protected readonly icon = icon;
  protected readonly text = text;
  protected readonly labelClass = labelClass;
  protected readonly descriptionClass = descriptionClass;
  protected readonly on = linkedSignal(() => this.checked());
  private readonly generatedId = `markas-checkbox-${nextId++}`;
  protected readonly checkboxId = computed(() => this.id() ?? this.generatedId);
  protected readonly boxClass = computed(() =>
    [box, this.userClass()].filter(Boolean).join(" "),
  );

  protected toggle(value: boolean) {
    this.on.set(value);
    this.checkedChange.emit(value);
  }
}
```

```ts
import { Component, signal } from "@angular/core";
import { Checkbox } from "./markas/checkbox.component";

@Component({
  selector: "app-preferences",
  imports: [Checkbox],
  template: `
    <markas-checkbox
      [(checked)]="updates"
      name="updates"
      label="Send me product updates"
      description="At most one email per month."
    />
  `,
})
export class Preferences {
  readonly updates = signal(false);
}
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | - | Label text next to the box, linked through for/id. |
| `description` | `string` | - | Supporting text below the label, linked through aria-describedby. |
| `checked / defaultChecked / v-model / bind:checked` | `boolean` | false | Checked state. Blade and Astro use the checked attribute, React checked or defaultChecked, Vue v-model, Svelte bind:checked, Angular checked or [(checked)]. |
| `disabled` | `boolean` | false | Disables the checkbox and dims the label. |
| `id` | `string` | auto | Input id. Generated when empty. |
| `checkedChange` | `output<boolean>` | - | Angular only. Emits the new state every time the checkbox changes. |

## Accessibility

- Uses a native checkbox input, so Space toggles it and screen readers announce its state.
- The label is linked through for and id, so clicking the label toggles the box too.
- The check icon is decorative (aria-hidden), the visual state follows :checked.

## Notes

- Extra attributes (`name`, `value`, `required`, `class`) go to the `<input>` element.
- The checked look uses CSS `:checked` (the `checked:` and `peer-checked:` variants), not `data-state`, so it stays correct without JavaScript.
- The component has no built-in text. Translate `label` and `description` directly.
