On this page

Checkbox

---
import { Checkbox } from "@/components/starwind/checkbox";
---

<Checkbox id="demo-checkbox" label="Checkbox" />

import { Checkbox } from "@/components/starwind/checkbox";

export function Example() {
  return (
    <Checkbox id="demo-checkbox" label="Checkbox" />
  );
}

Installation

pnpx starwind@latest add checkbox

npx starwind@latest add checkbox

yarn dlx starwind@latest add checkbox

Framework Availability

Astro Available React Available

Checkbox is available for Astro and React.

Usage

variant

Default

Primary

Secondary

Info

Success

Warning

Error

---
import { Checkbox } from "@/components/starwind/checkbox";
---

<Checkbox id="default" label="Default" variant="default" defaultChecked />
<Checkbox id="primary" label="Primary" variant="primary" defaultChecked />
<Checkbox id="secondary" label="Secondary" variant="secondary" defaultChecked />
<Checkbox id="info" label="Info" variant="info" defaultChecked />
<Checkbox id="success" label="Success" variant="success" defaultChecked />
<Checkbox id="warning" label="Warning" variant="warning" defaultChecked />
<Checkbox id="error" label="Error" variant="error" defaultChecked />

Runtime example adjustment

Use defaultChecked for mutable uncontrolled examples. checked is reserved for a framework adapter that owns and resynchronizes controlled state.

size

Small

Medium

Large

---
import { Checkbox } from "@/components/starwind/checkbox";
---

<Checkbox id="small" label="Small" size="sm" />
<Checkbox id="medium" label="Medium" size="md" />
<Checkbox id="large" label="Large" size="lg" />

disabled

Disabled

Disabled Checked

---
import { Checkbox } from "@/components/starwind/checkbox";
---

<Checkbox id="disabled" label="Disabled" disabled />
<Checkbox id="disabled-checked" label="Disabled Checked" disabled defaultChecked />

Runtime example adjustment

The disabled checked example also uses defaultChecked, preserving an uncontrolled initial state even though interaction is disabled.

API Reference

Styled Component API

These props are added or materially changed by the installed Astro styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Follow the Primitive and Runtime links for lower-level behavior props.

Checkbox

Inherits span attributes. Omits `defaultChecked`, `id`, and `onChange`.

Contains the following additional props:

Prop Type Default

defaultChecked boolean —

Description: Sets the initial checked state when the choice is uncontrolled.
Classification: Primitive override
Primitive prop: checkbox.Root.defaultChecked

label string —

Description: Provides accessible text for the component.
Classification: Wrapper prop

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Description: Selects the component's visual variant.
Classification: Styled variant

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Checkbox.

Primitive API

Checkbox Primitive

Runtime API

Checkbox primitive: createCheckbox from @starwind-ui/runtime/checkbox

Changelog

v2.0.0

Rebuilt Checkbox on Starwind Runtime for checked state, native form participation, and checked-change events.
See the Checkbox Primitive for the underlying unstyled anatomy and behavior API.

v1.4.3

Refactor tailwind variants functions into separate variants.ts file

v1.4.1

add aria-invalid styling

v1.4.0

style and focus state updates

v1.3.0

Add a data-slot attribute to all components to enable global styling updates

v1.2.0

No longer require an “id” prop
Adjust component to use type VariantProps from tailwind-variants. This provides greater type safety and cleans up component frontmatter.

v1.1.0

tailwind-variants now implemented. This uses tailwind-merge under the hood to merge Tailwind classes without style conflicts, allowing you to override any existing classes using the “class” prop.