Toggle

A lightweight, accessible toggle component for Astro, perfect for managing binary UI states like likes, bookmarks, and switches. Fully customizable with Tailwind CSS.

Install

pnpm dlx hybrid-astro-ui@latest add toggle

npx hybrid-astro-ui@latest add toggle

yarn dlx hybrid-astro-ui@latest add toggle

bunx hybrid-astro-ui@latest add toggle

Usage

---
import Heart from "@lucide/astro/icons/heart"
import { 
    Toggle, 
    ToggleActive, 
    ToggleInactive 
} from "@/src/components/hybrid-astro-ui/toggle";

---
<Toggle id="like-btn">
    <ToggleActive>
        <Heart class="text-red-500 fill-current" />
    </ToggleActive>
    <ToggleInactive>
        <Heart />
    </ToggleInactive>
    <span>Like</span>
</Toggle>

Custom classes

---
import Menu from "@lucide/astro/icons/menu"
import X from "@lucide/astro/icons/x"
import { 
    Toggle, 
    ToggleActive, 
    ToggleInactive 
} from "@/src/components/hybrid-astro-ui/toggle";
---
<Toggle id="menu-btn" class="border-none bg-transparent [&_svg]:h-7 [&_svg]:w-7 p-0">
    <ToggleActive>
        <X />
    </ToggleActive>
    <ToggleInactive>
        <Menu />
    </ToggleInactive>
</Toggle>

Toggle (Root)

Toggle is the core component that manages the toggle state. It renders a real checkbox internally and exposes its state using CSS only, without JavaScript.

This component is responsible for:

• Handling the checked / unchecked state
• Managing accessibility and focus
• Exposing the state to ToggleActive and ToggleInactive
• Allowing progressive enhancement with JavaScript when needed

Props

• class: Optional utility classes applied to the root element. Useful for styling, layout adjustments, or icon-only toggles.
• active: Sets the initial checked state of the toggle. This is the default state on first render.
• id: Assigns an ID to the internal checkbox. This allows external JavaScript to access or listen to the toggle state if needed.
• value: The value submitted when the toggle is used inside a form. This does not affect the visual state.
• name: Associates the toggle with a form field name. Useful when grouping toggles or submitting form data.
• disabled: Disables user interaction and applies disabled visual styles. The toggle cannot be changed while disabled.

Toggle is designed as a low-level primitive and can be used for likes, bookmarks, switches, menus, and other binary UI states.

ToggleActive

ToggleActive renders its content only when the toggle is in the active (checked) state. It does not accept props and does not manage state by itself. Instead, it reacts to the internal state exposed by Toggle.

Typical use cases include:

• Showing an active icon (filled heart, active bookmark)
• Displaying “On” or “Enabled” labels
• Rendering alternative UI for the active state

ToggleInactive

ToggleInactive renders its content only when the toggle is in the inactive (unchecked) state. Like ToggleActive, it does not accept props and relies entirely on the parent Toggle for state.

Typical use cases include:

• Showing an inactive icon (outline heart, empty bookmark)
• Displaying “Off” or “Disabled” labels
• Rendering the default UI before interaction

Design philosophy

Together, these three components form a simple but powerful pattern:

• Toggle manages state
• ToggleActive renders the active UI
• ToggleInactive renders the inactive UI

This approach keeps markup readable, avoids JavaScript by default, and fits perfectly into static and hybrid Astro projects.