```astro --- import { Button } from "@/components/starwind/button"; import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, } from "@/components/starwind/dialog"; import { Input } from "@/components/starwind/input"; import { Label } from "@/components/starwind/label"; import { Textarea } from "@/components/starwind/textarea"; ---

Subject

Message

</div>
      </div>
      <DialogFooter>
        <DialogClose asChild>
          <Button type="button" variant="outline">Cancel</Button>
        </DialogClose>
        <Button type="submit">Send Message</Button>
      </DialogFooter>
    </form>
  </DialogContent>
</Dialog>

<div class="mt-8">
  <p class="text-muted-foreground mb-2 text-sm">
    This button is outside the Dialog component but opens the same dialog:
  </p>
  <DialogTrigger targetId="contact-us-dialog" class="mt-2" asChild>
    <Button variant="primary">Contact Us (External)</Button>
  </DialogTrigger>
</div>

form.addEventListener("submit", (e) => {
      e.preventDefault();
      const formData = new FormData(form);
      const formValues = Object.fromEntries(formData.entries());

// demo form data logging
      console.log("Form submission values:", formValues);

// You can add additional logic here like:
      // - Form validation
      // - API submission
      // - Success/error handling
    });
  };

setupForm();

export function Example() {
  function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    console.log(
      "Form submission values:",
      Object.fromEntries(new FormData(event.currentTarget).entries()),
    );
  }

return (
    <>
      <Dialog id="contact-us-dialog">
        <DialogTrigger asChild><Button variant="outline">Contact Us</Button></DialogTrigger>
        <DialogContent className="sm:max-w-[450px]">
          <form className="flex flex-col gap-4" onSubmit={handleSubmit}>
            <DialogHeader>
              <DialogTitle>Contact Us</DialogTitle>
              <DialogDescription>Send us a message and we'll get back to you shortly.</DialogDescription>
            </DialogHeader>
            <div className="grid gap-6 py-4">
              <div className="grid gap-2">
                <Label htmlFor="email">Email</Label>
                <Input id="email" name="email" type="email" placeholder="your@email.com" />
              </div>
              <div className="grid gap-2">
                <Label htmlFor="subject">Subject</Label>
                <Input id="subject" name="subject" placeholder="How can we help?" />
              </div>
              <div className="grid gap-2">
                <Label htmlFor="message">Message</Label>
                <Textarea id="message" name="message" placeholder="Tell us what you need..." className="min-h-[80px]" />
              </div>
            </div>
            <DialogFooter>
              <DialogClose asChild><Button type="button" variant="outline">Cancel</Button></DialogClose>
              <Button type="submit">Send Message</Button>
            </DialogFooter>
          </form>
        </DialogContent>
      </Dialog>
      <div className="mt-8">
        <p className="text-muted-foreground mb-2 text-sm">
          This button is outside the Dialog component but opens the same dialog:
        </p>
        <DialogTrigger targetId="contact-us-dialog" className="mt-2" asChild>
          <Button variant="primary">Contact Us (External)</Button>
        </DialogTrigger>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Nested Dialogs

<DocsBadge variant="info" text="New" size="md" class="mr-1" /> You can nest dialogs within other dialogs to create multi-level workflows. The nested dialog will appear on top of the parent dialog, and only the topmost dialog will close when pressing Escape or clicking outside.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/starwind/dialog";
---

<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Open Parent Dialog</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Parent Dialog</DialogTitle>
      <DialogDescription>
        This is the parent dialog. You can open a nested dialog from here.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter class="mt-4">
      <Dialog>
        <DialogTrigger asChild>
          <Button class="w-full sm:w-auto">Open Nested</Button>
        </DialogTrigger>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>Nested Dialog</DialogTitle>
            <DialogDescription>
              This is the nested dialog. The parent will not close when clicking outside.</DialogDescription
            >
          </DialogHeader>
          <DialogFooter class="mt-4">
            <DialogClose asChild>
              <Button variant="outline">Close Nested</Button>
            </DialogClose>
          </DialogFooter>
        </DialogContent>
      </Dialog>
      <DialogClose asChild>
        <Button variant="outline" class="w-full sm:w-auto">Close Parent</Button>
      </DialogClose>
    </DialogFooter>
  </DialogContent>
</Dialog>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/starwind/dialog";

export function Example() {
  return (
    <>
      <Dialog>
        <DialogTrigger asChild>
          <Button variant="outline">Open Parent Dialog</Button>
        </DialogTrigger>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>Parent Dialog</DialogTitle>
            <DialogDescription>
              This is the parent dialog. You can open a nested dialog from here.
            </DialogDescription>
          </DialogHeader>
          <DialogFooter className="mt-4">
            <Dialog>
              <DialogTrigger asChild>
                <Button className="w-full sm:w-auto">Open Nested</Button>
              </DialogTrigger>
              <DialogContent>
                <DialogHeader>
                  <DialogTitle>Nested Dialog</DialogTitle>
                  <DialogDescription>
                    This is the nested dialog. The parent will not close when clicking outside.</DialogDescription
                  >
                </DialogHeader>
                <DialogFooter className="mt-4">
                  <DialogClose asChild>
                    <Button variant="outline">Close Nested</Button>
                  </DialogClose>
                </DialogFooter>
              </DialogContent>
            </Dialog>
            <DialogClose asChild>
              <Button variant="outline" className="w-full sm:w-auto">Close Parent</Button>
            </DialogClose>
          </DialogFooter>
        </DialogContent>
      </Dialog>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Dialog
- Inherits div attributes.

### DialogTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Wrapper prop | Merges the component behavior and props into its child element. |
- Inherits button attributes.

### DialogContent
- Inherits dialog attributes.

### DialogHeader
- Inherits div attributes.

### DialogFooter
- Inherits div attributes.

### DialogTitle
- Inherits h2 attributes.

### DialogDescription
- Inherits p attributes.

### DialogClose
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Wrapper prop | Merges the component behavior and props into its child element. |
- Inherits button attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Dialog Primitive](/docs/primitives/dialog/)
- Runtime factory: [`createDialog`](/docs/runtime/#create-dialog) from `@starwind-ui/runtime/dialog`

## Changelog

### v2.0.2

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.0

- Rebuilt Dialog on Starwind Runtime for modal state, focus management, dismissal, and nesting.
- See the [Dialog Primitive](/docs/primitives/dialog/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/dropdown/](https://starwind.dev/docs/components/dropdown/) · [Markdown](https://starwind.dev/docs/components/dropdown.md)

# Dropdown

Dropdown,
DropdownContent,
DropdownItem,
DropdownLabel,
DropdownLinkItem,
DropdownSeparator,
DropdownShortcut,
DropdownSub,
DropdownSubContent,
DropdownSubTrigger,
DropdownTrigger,
} from "@/components/starwind/dropdown";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownLabel, DropdownSeparator } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button>Open Menu</Button>
  </DropdownTrigger>
  <DropdownContent>
    <DropdownLabel>My Account</DropdownLabel>
    <DropdownSeparator />
    <DropdownItem>Profile</DropdownItem>
    <DropdownItem>Settings</DropdownItem>
    <DropdownSeparator />
    <DropdownItem>Help</DropdownItem>
    <DropdownItem disabled>Sign out</DropdownItem>
  </DropdownContent>
</Dropdown>
```
  </div>
  <div slot="react">
```tsx
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownLabel, DropdownSeparator } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <Dropdown>
      <DropdownTrigger asChild>
        <Button>Open Menu</Button>
      </DropdownTrigger>
      <DropdownContent>
        <DropdownLabel>My Account</DropdownLabel>
        <DropdownSeparator />
        <DropdownItem>Profile</DropdownItem>
        <DropdownItem>Settings</DropdownItem>
        <DropdownSeparator />
        <DropdownItem>Help</DropdownItem>
        <DropdownItem disabled>Sign out</DropdownItem>
      </DropdownContent>
    </Dropdown>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add dropdown
```

## Usage

### Action Menu

A common use case is a compact list of application actions. Each `DropdownItem` participates in the Runtime menu's keyboard navigation and selection behavior.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button>Navigation</Button>
  </DropdownTrigger>
  <DropdownContent align="center">
    <DropdownItem>Open dashboard</DropdownItem>
    <DropdownItem>Create project</DropdownItem>
    <DropdownItem>Invite teammate</DropdownItem>
    <DropdownItem>View activity</DropdownItem>
    <DropdownItem>Account settings</DropdownItem>
  </DropdownContent>
</Dropdown>
```
  </div>
  <div slot="react">
```tsx
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Dropdown>
        <DropdownTrigger asChild>
          <Button>Navigation</Button>
        </DropdownTrigger>
        <DropdownContent align="center">
          <DropdownItem>Open dashboard</DropdownItem>
          <DropdownItem>Create project</DropdownItem>
          <DropdownItem>Invite teammate</DropdownItem>
          <DropdownItem>View activity</DropdownItem>
          <DropdownItem>Account settings</DropdownItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Link Items

Use `DropdownItem` for commands in the current interface and `DropdownLinkItem` for navigation. Link items render native anchors, accept normal anchor attributes, and participate in the same keyboard navigation and highlighting as action items.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Dropdown, DropdownTrigger, DropdownContent, DropdownLinkItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button variant="outline">Resources</Button>
  </DropdownTrigger>
  <DropdownContent align="center">
    <DropdownLinkItem href="/docs/">Documentation</DropdownLinkItem>
    <DropdownLinkItem href="/docs/getting-started/">Getting started</DropdownLinkItem>
    <DropdownLinkItem href="/docs/components/dropdown/" disabled>
      Disabled destination
    </DropdownLinkItem>
  </DropdownContent>
</Dropdown>
```
  </div>
  <div slot="react">
```tsx
import { Dropdown, DropdownTrigger, DropdownContent, DropdownLinkItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <Dropdown>
      <DropdownTrigger asChild>
        <Button variant="outline">Resources</Button>
      </DropdownTrigger>
      <DropdownContent align="center">
        <DropdownLinkItem href="/docs/">Documentation</DropdownLinkItem>
        <DropdownLinkItem href="/docs/getting-started/">Getting started</DropdownLinkItem>
        <DropdownLinkItem href="/docs/components/dropdown/" disabled>
          Disabled destination
        </DropdownLinkItem>
      </DropdownContent>
    </Dropdown>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

Disabled link items omit their `href` and expose the same disabled state as other menu items. `DropdownLinkItem` keeps the menu open by default; set `closeOnClick` when navigation does not unload the current page and the menu should close immediately.

### Hover Open

The dropdown can be configured to open on hover in addition to click.

<Dropdown openOnHover closeDelay={300}>
  <DropdownTrigger asChild>
    <Button>Hover Me</Button>
  </DropdownTrigger>
  <DropdownContent>
    <DropdownLabel>My Account</DropdownLabel>
    <DropdownSeparator />
    <DropdownItem>Profile</DropdownItem>
    <DropdownItem>Settings</DropdownItem>
    <DropdownSeparator />
    <DropdownItem>Help</DropdownItem>
    <DropdownItem disabled>Sign out</DropdownItem>
  </DropdownContent>
</Dropdown>
```
  </div>
  <div slot="react">
```tsx
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownLabel, DropdownSeparator } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Dropdown openOnHover closeDelay={300}>
        <DropdownTrigger asChild>
          <Button>Hover Me</Button>
        </DropdownTrigger>
        <DropdownContent>
          <DropdownLabel>My Account</DropdownLabel>
          <DropdownSeparator />
          <DropdownItem>Profile</DropdownItem>
          <DropdownItem>Settings</DropdownItem>
          <DropdownSeparator />
          <DropdownItem>Help</DropdownItem>
          <DropdownItem disabled>Sign out</DropdownItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Submenu

Use `DropdownSub`, `DropdownSubTrigger`, and `DropdownSubContent` to nest secondary actions.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  Dropdown,
  DropdownContent,
  DropdownItem,
  DropdownSeparator,
  DropdownShortcut,
  DropdownSub,
  DropdownSubContent,
  DropdownSubTrigger,
  DropdownTrigger,
} from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button variant="outline">Open</Button>
  </DropdownTrigger>
  <DropdownContent class="min-w-[10rem]">
    <DropdownItem>Team</DropdownItem>
    <DropdownSub>
      <DropdownSubTrigger>Invite users</DropdownSubTrigger>
      <DropdownSubContent>
        <DropdownItem>Email</DropdownItem>
        <DropdownItem>Message</DropdownItem>
        <DropdownSub>
          <DropdownSubTrigger>More options</DropdownSubTrigger>
          <DropdownSubContent>
            <DropdownItem>Calendly</DropdownItem>
            <DropdownItem>Slack</DropdownItem>
            <DropdownSeparator />
            <DropdownItem>Webhook</DropdownItem>
          </DropdownSubContent>
        </DropdownSub>
        <DropdownSeparator />
        <DropdownItem>Advanced...</DropdownItem>
      </DropdownSubContent>
    </DropdownSub>
    <DropdownItem>
      <span>New Team</span>
      <DropdownShortcut>⌘+T</DropdownShortcut>
    </DropdownItem>
  </DropdownContent>
</Dropdown>
```
  </div>
  <div slot="react">
```tsx
import {
  Dropdown,
  DropdownContent,
  DropdownItem,
  DropdownSeparator,
  DropdownShortcut,
  DropdownSub,
  DropdownSubContent,
  DropdownSubTrigger,
  DropdownTrigger,
} from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Dropdown>
        <DropdownTrigger asChild>
          <Button variant="outline">Open</Button>
        </DropdownTrigger>
        <DropdownContent className="min-w-[10rem]">
          <DropdownItem>Team</DropdownItem>
          <DropdownSub>
            <DropdownSubTrigger>Invite users</DropdownSubTrigger>
            <DropdownSubContent>
              <DropdownItem>Email</DropdownItem>
              <DropdownItem>Message</DropdownItem>
              <DropdownSub>
                <DropdownSubTrigger>More options</DropdownSubTrigger>
                <DropdownSubContent>
                  <DropdownItem>Calendly</DropdownItem>
                  <DropdownItem>Slack</DropdownItem>
                  <DropdownSeparator />
                  <DropdownItem>Webhook</DropdownItem>
                </DropdownSubContent>
              </DropdownSub>
              <DropdownSeparator />
              <DropdownItem>Advanced...</DropdownItem>
            </DropdownSubContent>
          </DropdownSub>
          <DropdownItem>
            <span>New Team</span>
            <DropdownShortcut>⌘+T</DropdownShortcut>
          </DropdownItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Shortcuts

Add `DropdownShortcut` to display keyboard hints alongside actions.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  Dropdown,
  DropdownContent,
  DropdownItem,
  DropdownLabel,
  DropdownSeparator,
  DropdownShortcut,
  DropdownTrigger,
} from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button variant="outline">Open</Button>
  </DropdownTrigger>
  <DropdownContent>
    <DropdownLabel>My Account</DropdownLabel>
    <DropdownItem>
      <span>Profile</span>
      <DropdownShortcut>⇧⌘P</DropdownShortcut>
    </DropdownItem>
    <DropdownItem>
      <span>Billing</span>
      <DropdownShortcut>⌘B</DropdownShortcut>
    </DropdownItem>
    <DropdownItem>
      <span>Settings</span>
      <DropdownShortcut>⌘S</DropdownShortcut>
    </DropdownItem>
    <DropdownSeparator />
    <DropdownItem>
      <span>Log out</span>
      <DropdownShortcut>⇧⌘Q</DropdownShortcut>
    </DropdownItem>
  </DropdownContent>
</Dropdown>
```
  </div>
  <div slot="react">
```tsx
import {
  Dropdown,
  DropdownContent,
  DropdownItem,
  DropdownLabel,
  DropdownSeparator,
  DropdownShortcut,
  DropdownTrigger,
} from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Dropdown>
        <DropdownTrigger asChild>
          <Button variant="outline">Open</Button>
        </DropdownTrigger>
        <DropdownContent>
          <DropdownLabel>My Account</DropdownLabel>
          <DropdownItem>
            <span>Profile</span>
            <DropdownShortcut>⇧⌘P</DropdownShortcut>
          </DropdownItem>
          <DropdownItem>
            <span>Billing</span>
            <DropdownShortcut>⌘B</DropdownShortcut>
          </DropdownItem>
          <DropdownItem>
            <span>Settings</span>
            <DropdownShortcut>⌘S</DropdownShortcut>
          </DropdownItem>
          <DropdownSeparator />
          <DropdownItem>
            <span>Log out</span>
            <DropdownShortcut>⇧⌘Q</DropdownShortcut>
          </DropdownItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Placement Options

You can position the dropdown menu in different ways by customizing the `side` and `align` properties.

<div class="flex gap-4">
  <Dropdown>
    <DropdownTrigger asChild>
      <Button>Left (Start)</Button>
    </DropdownTrigger>
    <DropdownContent align="start">
      <DropdownItem>Option 1</DropdownItem>
      <DropdownItem>Option 2</DropdownItem>
      <DropdownItem>Option 3</DropdownItem>
    </DropdownContent>
  </Dropdown>
  <Dropdown>
    <DropdownTrigger asChild>
      <Button>Center</Button>
    </DropdownTrigger>
    <DropdownContent align="center">
      <DropdownItem>Option 1</DropdownItem>
      <DropdownItem>Option 2</DropdownItem>
      <DropdownItem>Option 3</DropdownItem>
    </DropdownContent>
  </Dropdown>
  <Dropdown>
    <DropdownTrigger asChild>
      <Button>Right (End)</Button>
    </DropdownTrigger>
    <DropdownContent align="end">
      <DropdownItem>Option 1</DropdownItem>
      <DropdownItem>Option 2</DropdownItem>
      <DropdownItem>Option 3</DropdownItem>
    </DropdownContent>
  </Dropdown>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <div className="flex gap-4">
        <Dropdown>
          <DropdownTrigger asChild>
            <Button>Left (Start)</Button>
          </DropdownTrigger>
          <DropdownContent align="start">
            <DropdownItem>Option 1</DropdownItem>
            <DropdownItem>Option 2</DropdownItem>
            <DropdownItem>Option 3</DropdownItem>
          </DropdownContent>
        </Dropdown>
        <Dropdown>
          <DropdownTrigger asChild>
            <Button>Center</Button>
          </DropdownTrigger>
          <DropdownContent align="center">
            <DropdownItem>Option 1</DropdownItem>
            <DropdownItem>Option 2</DropdownItem>
            <DropdownItem>Option 3</DropdownItem>
          </DropdownContent>
        </Dropdown>
        <Dropdown>
          <DropdownTrigger asChild>
            <Button>Right (End)</Button>
          </DropdownTrigger>
          <DropdownContent align="end">
            <DropdownItem>Option 1</DropdownItem>
            <DropdownItem>Option 2</DropdownItem>
            <DropdownItem>Option 3</DropdownItem>
          </DropdownContent>
        </Dropdown>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### With Icons

You can add icons to dropdown items for better visual cues.

<Dropdown>
  <DropdownTrigger asChild>
    <Button>Actions</Button>
  </DropdownTrigger>
  <DropdownContent>
    <DropdownLabel>Actions</DropdownLabel>
    <DropdownSeparator />
    <DropdownItem>
      <Copy />
      Copy
    </DropdownItem>
    <DropdownItem>
      <Edit />
      Edit
    </DropdownItem>
    <DropdownSeparator />
    <DropdownLabel>Danger Zone</DropdownLabel>
    <DropdownItem inset>Archive</DropdownItem>
    <DropdownItem inset disabled>Delete</DropdownItem>
  </DropdownContent>
</Dropdown>
```
  </div>
  <div slot="react">
```tsx
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownLabel, DropdownSeparator } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
import { IconCopy as Copy } from "@tabler/icons-react";
import { IconEdit as Edit } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <Dropdown>
        <DropdownTrigger asChild>
          <Button>Actions</Button>
        </DropdownTrigger>
        <DropdownContent>
          <DropdownLabel>Actions</DropdownLabel>
          <DropdownSeparator />
          <DropdownItem>
            <Copy />
            Copy
          </DropdownItem>
          <DropdownItem>
            <Edit />
            Edit
          </DropdownItem>
          <DropdownSeparator />
          <DropdownLabel>Danger Zone</DropdownLabel>
          <DropdownItem inset>Archive</DropdownItem>
          <DropdownItem inset disabled>Delete</DropdownItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Dropdown
- Inherits div attributes.

### DropdownTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Primitive override | Merges the component behavior and props into its child element. |
- Inherits button attributes.

### DropdownContent
- Inherits div attributes.

### DropdownItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
- Inherits div attributes.

### DropdownLinkItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `closeOnClick` | `boolean` | No | `false` | Wrapper prop | Closes the containing surface after the item is activated. |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
- Inherits a attributes.

### DropdownCheckboxItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `closeOnClick` | `boolean` | No | `false` | Wrapper prop | Closes the containing surface after the item is activated. |
| `indicatorClass` | `string` | No | - | Wrapper prop | Adds classes to the generated selection indicator. |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
| `showIndicator` | `boolean` | No | `true` | Wrapper prop | Shows the generated selection indicator. |
- Inherits div attributes. Omits `aria-checked` and `role`.

### DropdownCheckboxItemIndicator
- Inherits span attributes.

### DropdownRadioGroup
- Inherits div attributes.

### DropdownRadioItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `closeOnClick` | `boolean` | No | `false` | Wrapper prop | Closes the containing surface after the item is activated. |
| `indicatorClass` | `string` | No | - | Wrapper prop | Adds classes to the generated selection indicator. |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
| `showIndicator` | `boolean` | No | `true` | Wrapper prop | Shows the generated selection indicator. |
| `value` | `string` | Yes | - | Wrapper prop | Controls or identifies the component value. |
- Inherits div attributes. Omits `aria-checked` and `role`.

### DropdownRadioItemIndicator
- Inherits span attributes.

### DropdownGroup
- Inherits div attributes.

### DropdownLabel
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
- Inherits div attributes.

### DropdownSeparator
- Inherits div attributes.

### DropdownShortcut
- Inherits span attributes.

### DropdownSub
- Inherits div attributes.

### DropdownSubTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
- Inherits div attributes.

### DropdownSubContent
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | No | `"right"` | Primitive override | Selects the preferred side for floating content. |
| `sideOffset` | `number` | No | `0` | Primitive override | Sets the distance in pixels between floating content and its anchor. |
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Menu Primitive](/docs/primitives/menu/)
- Runtime factory: [`createMenu`](/docs/runtime/#create-menu) from `@starwind-ui/runtime/menu`

## Changelog

### v3.1.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v3.1.0

- Added `DropdownLinkItem` for native anchor navigation; replace legacy `DropdownItem as="a"` usage with this dedicated part.

### v3.0.0

- Rebuilt Dropdown on Starwind Runtime while preserving its styled API over the shared Menu behavior.
- See the [Menu Primitive](/docs/primitives/menu/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/dropzone/](https://starwind.dev/docs/components/dropzone/) · [Markdown](https://starwind.dev/docs/components/dropzone.md)

# Dropzone

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
---

<div class="w-full max-w-[400px]">
  <Dropzone />
</div>
```
  </div>
  <div slot="react">
```tsx
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";

export function Example() {
  return (
    <div className="w-full max-w-[400px]">
      <Dropzone />
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add dropzone
```

## Usage

> **Info:** No dropped files on this page are uploaded anywhere.

### Default

The default Dropzone component displays a cloud upload icon with a prompt to upload files, and shows what files have been selected.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
---

<Dropzone />
```
  </div>
  <div slot="react">
```tsx
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";

export function Example() {
  return (
    <>
      <Dropzone />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Custom Content

The dropzone components can be customized through slots. The default `<Dropzone />` component has the following three components in the slot if nothing is passed:

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<DropzoneUploadIndicator />
<DropzoneLoadingIndicator />
<DropzoneFilesList />
```
</div>
<div slot="react">
```tsx
import { DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";

export function Example() {
  return (
    <>
      <DropzoneUploadIndicator />
      <DropzoneLoadingIndicator />
      <DropzoneFilesList />
    </>
  );
}
```
</div>
</FrameworkCodeSwitcher>

The `DropzoneUploadIndicator` and `DropzoneLoadingIndicator` each have their own slots to customize the upload and loading indicators. The `DropzoneFilesList` component can be passed any classes to use.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
---

<Dropzone>
  <DropzoneUploadIndicator>
    <span class="my-6 text-lg">Your specific message</span>
  </DropzoneUploadIndicator>
  <DropzoneLoadingIndicator />
  <DropzoneFilesList />
</Dropzone>
```
  </div>
  <div slot="react">
```tsx
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";

export function Example() {
  return (
    <>
      <Dropzone>
        <DropzoneUploadIndicator>
          <span className="my-6 text-lg">Your specific message</span>
        </DropzoneUploadIndicator>
        <DropzoneLoadingIndicator />
        <DropzoneFilesList />
      </Dropzone>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Loading

Nothing is actually uploaded when a file is selected, as internally a standard html `<input type="file">` is used. To show a loading indication initially, you can use the `isUploading` prop.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
---

<Dropzone isUploading={true} />
```
  </div>
  <div slot="react">
```tsx
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";

export function Example() {
  return (
    <>
      <Dropzone isUploading={true} />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

You can also use the `data-is-uploading` attribute to show or hide a loading indicator at any time. This is useful if you want to show a loading indicator while a file is actually being uploaded (like on form submission).

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import {
  Dropzone,
  DropzoneFilesList,
  DropzoneLoadingIndicator,
  DropzoneUploadIndicator,
} from "@/components/starwind/dropzone";
---

<div class="flex w-full max-w-[400px] flex-col gap-4">
  <form id="dropzone-form-demo" class="space-y-4">
    <Dropzone id="my-dropzone" name="dropzone-file" />
    <Button type="submit" class="w-full">Submit</Button>
  </form>
</div>

dropzone.setAttribute("data-is-uploading", "true");

const formData = new FormData(form);
        const formValues = Object.fromEntries(formData.entries());

// demo form data logging
        console.log("Form submission values:", formValues);

// You can add additional logic here like:
        // - Form validation
        // - API submission
        // - Success/error handling

// Simulate API submission
        setTimeout(() => {
          dropzone.setAttribute("data-is-uploading", "false");
        }, 2000);
      });
    }
  }

handleFormSubmit();

document.addEventListener("astro:after-swap", handleFormSubmit);
</script>

```
  </div>
  <div slot="react">
```tsx
import type { FormEvent } from "react";
import { useState } from "react";
import { Button } from "@/components/starwind/button";
import { Dropzone } from "@/components/starwind/dropzone";

export function Example() {
  const [isUploading, setIsUploading] = useState(false);

async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setIsUploading(true);
    console.log(
      "Form submission values:",
      Object.fromEntries(new FormData(event.currentTarget).entries()),
    );
    await new Promise((resolve) => setTimeout(resolve, 2000));
    setIsUploading(false);
  }

return (
    <div className="flex w-full max-w-[400px] flex-col gap-4">
      <form className="space-y-4" onSubmit={handleSubmit}>
        <Dropzone name="dropzone-file" isUploading={isUploading} />
        <Button type="submit" className="w-full">Submit</Button>
      </form>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Accept Specific File Types

You can limit the types of files that users can select by using the `accept` attribute.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
---

<Dropzone accept="image/*" />
```
  </div>
  <div slot="react">
```tsx
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";

export function Example() {
  return (
    <>
      <Dropzone accept="image/*" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Multiple Files

Allow users to select multiple files by using the `multiple` attribute.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
---

<Dropzone multiple />
```
  </div>
  <div slot="react">
```tsx
import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";

export function Example() {
  return (
    <>
      <Dropzone multiple />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Dropzone
- Inherits input attributes. Omits `disabled` and `type`.

### DropzoneUploadIndicator
- Inherits div attributes.

### DropzoneLoadingIndicator
- Inherits div attributes.

### DropzoneFilesList
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Dropzone Primitive](/docs/primitives/dropzone/)
- Runtime factory: [`createDropzone`](/docs/runtime/#create-dropzone) from `@starwind-ui/runtime/dropzone`

## Changelog

### v2.0.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.0

- Rebuilt Dropzone on Starwind Runtime for drag-and-drop, file input, and component state handling.
- See the [Dropzone Primitive](/docs/primitives/dropzone/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/field/](https://starwind.dev/docs/components/field/) · [Markdown](https://starwind.dev/docs/components/field.md)

# Field

Field,
FieldControl,
FieldDescription,
FieldError,
FieldGroup,
FieldItem,
FieldLabel,
FieldLegend,
FieldSeparator,
FieldSet,
FieldValidity,
} from "@/components/starwind/field";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldLabel,
  FieldValidity,
} from "@/components/starwind/field";
---

<Field name="displayName">
  <FieldLabel>Display name</FieldLabel>
  <FieldControl required minlength="2" />
  <FieldDescription>This name appears on your profile.</FieldDescription>
  <FieldError match="valueMissing">Enter a display name.</FieldError>
  <FieldError match="tooShort">Use at least two characters.</FieldError>
  <FieldValidity match="valid">Looks good.</FieldValidity>
</Field>
```
  </div>
  <div slot="react">
```tsx
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldLabel,
  FieldValidity,
} from "@/components/starwind/field";

export function Example() {
  return (
    <Field name="displayName">
      <FieldLabel>Display name</FieldLabel>
      <FieldControl required minLength={2} />
      <FieldDescription>This name appears on your profile.</FieldDescription>
      <FieldError match="valueMissing">Enter a display name.</FieldError>
      <FieldError match="tooShort">Use at least two characters.</FieldError>
      <FieldValidity match="valid">Looks good.</FieldValidity>
    </Field>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add field
```

## Usage

For complete validation policies, custom and asynchronous validation, schema adapters, and submission flows using `Field` and `FieldSet`, see the [Form examples](/docs/components/form/).

### Groups and non-input controls

Use `FieldSet` with `FieldLegend` when several controls answer one question or belong to the same settings section. `FieldItem` gives checkboxes, radios, and other non-text controls the same label, description, validation, disabled-state, and layout conventions as text inputs.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
<FieldSet>
  <FieldLegend>Preferences</FieldLegend>
  <FieldGroup>
    <Field name="updates" orientation="horizontal">
      <FieldItem>
        <Checkbox id="field-updates" value="yes" />
        <FieldLabel for="field-updates">Product updates</FieldLabel>
      </FieldItem>
    </Field>
  </FieldGroup>
</FieldSet>
```
  </div>
  <div slot="react">
```tsx
import { Checkbox } from "@/components/starwind/checkbox";
import { Field, FieldGroup, FieldItem, FieldLabel, FieldLegend, FieldSet } from "@/components/starwind/field";

export function Example() {
  return (
    <>
      <FieldSet>
        <FieldLegend>Preferences</FieldLegend>
        <FieldGroup>
          <Field name="updates" orientation="horizontal">
            <FieldItem>
              <Checkbox id="field-updates" value="yes" />
              <FieldLabel htmlFor="field-updates">Product updates</FieldLabel>
            </FieldItem>
          </Field>
        </FieldGroup>
      </FieldSet>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Field
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `errorVisibility` | `"blur" \| "change" \| "manual" \| "submit"` | No | - | Primitive override | Selects whether semantic change, blur, submit, or manual validation reveals errors; inherits the owning Form policy when omitted. |
| `orientation` | `"horizontal" \| "responsive" \| "vertical"` | No | `"vertical"` | Styled variant | Selects the horizontal or vertical layout direction. |
| `revalidationTiming` | `"blur" \| "change" \| "manual" \| "submit"` | No | - | Primitive override | After an owning Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; inherits the owning Form policy when omitted. |
| `validationTiming` | `"blur" \| "change" \| "manual" \| "submit"` | No | - | Primitive override | Selects semantic change, blur, submit, or manual validation before an owning Form submission attempt; inherits the owning Form policy when omitted. |
- Inherits div attributes.

### FieldSet
- Inherits fieldset attributes.

### FieldLegend
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `"label" \| "legend"` | No | `"legend"` | Styled variant | Selects the component's visual variant. |
- Inherits div attributes.

### FieldGroup
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `"default" \| "outline"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits div attributes.

### FieldContent
- Inherits div attributes.

### FieldTitle
- Inherits div attributes.

### FieldLabel
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits label attributes.

### FieldControl
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultValue` | `string \| number \| string[]` | No | - | Wrapper prop | Sets the initial value when the component is uncontrolled. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `value` | `string \| number \| string[]` | No | - | Wrapper prop | Controls or identifies the component value. |
- Inherits input attributes. Omits `children`, `defaultValue`, `size`, and `value`.

### FieldDescription
- Inherits p attributes.

### FieldError
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `match` | `boolean \| "badInput" \| "customError" \| "patternMismatch" \| "rangeOverflow" \| "rangeUnderflow" \| "stepMismatch" \| "tooLong" \| "tooShort" \| "typeMismatch" \| "valid" \| "valueMissing"` | No | - | Primitive override | Selects the validation state that renders this message. |
- Inherits div attributes.

### FieldValidity
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `match` | `boolean \| "badInput" \| "customError" \| "patternMismatch" \| "rangeOverflow" \| "rangeUnderflow" \| "stepMismatch" \| "tooLong" \| "tooShort" \| "typeMismatch" \| "valid" \| "valueMissing"` | No | - | Wrapper prop | Selects the validation state that renders this message. |
- Inherits div attributes.

### FieldItem
- Inherits div attributes.

### FieldSeparator
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Field Primitive](/docs/primitives/field/)
- Primitive: [Fieldset Primitive](/docs/primitives/fieldset/)
- Runtime factory: [`createField`](/docs/runtime/#create-field) from `@starwind-ui/runtime/field`
- Runtime factory: [`createFieldset`](/docs/runtime/#create-fieldset) from `@starwind-ui/runtime/fieldset`

## Changelog

### v1.0.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v1.0.0

- Added the Runtime-backed Field family with validation, grouping, labels, descriptions, and accessible messages.
- See the [Field Primitive](/docs/primitives/field/) and [Fieldset Primitive](/docs/primitives/fieldset/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/form/](https://starwind.dev/docs/components/form/) · [Markdown](https://starwind.dev/docs/components/form.md)

# Form

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import {
  Field,
  FieldControl,
  FieldError,
  FieldGroup,
  FieldLabel,
} from "@/components/starwind/field";
import { Form, FormErrorSummary } from "@/components/starwind/form";
---

<div class="w-full max-w-md" data-profile-form>
  <Form>
    <FormErrorSummary aria-label="Profile errors">
      <p class="font-medium">Review the highlighted fields.</p>
    </FormErrorSummary>
    <FieldGroup>
      <Field name="email">
        <FieldLabel>Email</FieldLabel>
        <FieldControl type="email" required placeholder="you@example.com" />
        <FieldError match="valueMissing">Enter your email address.</FieldError>
        <FieldError match="typeMismatch">Enter a valid email address.</FieldError>
      </Field>
      <Button type="submit">Save profile</Button>
    </FieldGroup>
    <output class="text-muted-foreground mt-3 hidden text-sm" aria-live="polite"></output>
  </Form>
</div>

if (form) {
    form.addEventListener("submit", (event) => {
      event.preventDefault();
      const email = String(new FormData(form).get("email") ?? "");
      if (output) {
        output.value = `Submitted email: ${email}`;
        output.classList.remove("hidden");
        output.classList.add("block");
      }
    });
  }
</script>
```
  </div>
  <div slot="react">
```tsx
import { useState } from "react";
import { Button } from "@/components/starwind/button";
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
} from "@/components/starwind/field";
import { Form, FormErrorSummary } from "@/components/starwind/form";

export function Example() {
  const [submittedEmail, setSubmittedEmail] = useState<string | null>(null);

return (
    <div className="w-full max-w-md">
      <Form
        onSubmit={(event) => {
          event.preventDefault();
          const data = new FormData(event.currentTarget);
          setSubmittedEmail(String(data.get("email") ?? ""));
        }}
      >
        <FormErrorSummary aria-label="Profile errors">
          <p className="font-medium">Review the highlighted fields.</p>
        </FormErrorSummary>
        <FieldGroup>
          <Field name="email">
            <FieldLabel>Email</FieldLabel>
            <FieldControl
              type="email"
              required
              placeholder="you@example.com"
            />
            <FieldError match="valueMissing">Enter your email address.</FieldError>
            <FieldError match="typeMismatch">Enter a valid email address.</FieldError>
          </Field>
          <Button type="submit">Save profile</Button>
        </FieldGroup>
        {submittedEmail !== null && (
          <output className="text-muted-foreground mt-3 block text-sm" aria-live="polite">
            Submitted email: {submittedEmail}
          </output>
        )}
      </Form>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

Form remains a native HTML form. The Runtime adds validation timing, field coordination, and an
accessible error summary without requiring React or a form-state library.

## Installation

```bash
npx starwind@latest add form
```

## Start here

The browser still owns submission and `FormData`. Use ordinary `action`, `method`, `submit`, and
`reset` behavior; Runtime controls serialize through their installed hidden inputs.

> **Tip:** Most forms do not need to set a validation policy. Starwind waits until submit to validate and
reveal errors, then validates accepted corrections on change after the first submission attempt.

## Understand validation

Form separates two questions: when a Field is validated, and when an existing error is revealed.
Validation itself has a before-submit phase and an after-submit phase.

<ol class="not-content my-6 grid gap-3 sm:grid-cols-2">
<li class="border-border bg-card rounded-lg border p-4">
<p class="text-muted-foreground mb-1 text-xs font-semibold tracking-wide uppercase">1. Interact</p>
<p class="font-medium">A value changes, focus leaves a Field, the Form submits, or code requests validation.</p>
</li>
<li class="border-border bg-card rounded-lg border p-4">
<p class="text-muted-foreground mb-1 text-xs font-semibold tracking-wide uppercase">2. Validate</p>
<p class="font-medium">The current before- or after-submit timing decides whether validators run.</p>
</li>
<li class="border-border bg-card rounded-lg border p-4">
<p class="text-muted-foreground mb-1 text-xs font-semibold tracking-wide uppercase">3. Reveal</p>
<p class="font-medium">Error visibility independently decides whether existing errors may render.</p>
</li>
<li class="border-border bg-card rounded-lg border p-4">
<p class="text-muted-foreground mb-1 text-xs font-semibold tracking-wide uppercase">4. Continue</p>
<p class="font-medium">Valid submission proceeds; invalid submission focuses the first invalid Field.</p>
</li>
</ol>

### Validation policy

| Setting | What it controls | Default |
| --- | --- | --- |
| `validationTiming` | Interaction validation before the first submission attempt | `submit` |
| `revalidationTiming` | The interaction timing that replaces `validationTiming` after a submission attempt | `change` |
| `errorVisibility` | Which cause makes existing errors eligible to render | `submit` |

| Value | Meaning |
| --- | --- |
| `change` | Every accepted value revision from a native or Runtime control, including typing, selecting, checking, and sliding |
| `blur` | Focus leaves the entire Field, rather than moving between descendants of a composite Field |
| `submit` | A whole-Form submission attempt |
| `manual` | Imperative `validate()`; no automatic interaction matches it |

### Recommended policies

| Goal | Before submit | After submit | Reveal errors |
| --- | --- | --- | --- |
| Calm by default, responsive during correction | `submit` | `change` | `submit` |
| Live validation | `change` | `change` | `change` |
| Submit-only feedback | `submit` | `submit` | `submit` |
| Imperative wizard or step validation | `manual` | `manual` | `manual` |

<details class="not-content border-border my-6 rounded-lg border p-4">
<summary class="cursor-pointer font-medium">Phase and reset details</summary>
<div class="text-muted-foreground mt-3 space-y-3 text-sm">
<p>
  A successful or blocked submission attempt switches the whole Form to
  <code>revalidationTiming</code>, including Fields registered later. The phase does not change
  after a Field's first blur or first validation.
</p>
<p>
  Native reset or a full <code>resetValidation()</code> returns the Form to its before-submit
  phase. Changing a timing prop is prospective: it does not clear submission state, validation
  results, or already revealed errors.
</p>
</div>
</details>

<details class="not-content border-border my-6 rounded-lg border p-4">
<summary class="cursor-pointer font-medium">Coming from TanStack Form</summary>
<p class="text-muted-foreground mt-3 text-sm">
Conceptually, <code>validationTiming</code> is Starwind's before-submit mode and
<code>revalidationTiming</code> is its mode after submission. Starwind separately controls
sticky error revelation, ARIA descriptions, summaries, and invalid-field focus.
</p>
</details>

### Try a policy

Choose the before-submit trigger, its after-submit replacement, and the independent reveal trigger.
Form-level values apply to every Field unless that Field overrides one of them.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
} from "@/components/starwind/field";
import { Form, FormErrorSummary } from "@/components/starwind/form";
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/starwind/select";

const timings = ["submit", "blur", "change", "manual"] as const;
---

<div class="w-full max-w-lg" data-policy-demo>
  <div class="mb-6 grid gap-4 sm:grid-cols-2">
    <div class="space-y-2">
      <label class="text-sm font-medium" for="policy-validation">Before submit</label>
      <Select
        defaultValue="submit"
        data-policy-group="validation"
        data-policy-attribute="data-validation-timing"
      >
        <SelectTrigger id="policy-validation" class="w-full">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {timings.map((timing) => (
            <SelectItem value={timing}>
              {timing[0]?.toUpperCase() + timing.slice(1)}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
    <div class="space-y-2">
      <label class="text-sm font-medium" for="policy-revalidation">After submit</label>
      <Select
        defaultValue="change"
        data-policy-group="revalidation"
        data-policy-attribute="data-revalidation-timing"
      >
        <SelectTrigger id="policy-revalidation" class="w-full">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {timings.map((timing) => (
            <SelectItem value={timing}>
              {timing[0]?.toUpperCase() + timing.slice(1)}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
    <div class="space-y-2">
      <label class="text-sm font-medium" for="policy-visibility">Show errors</label>
      <Select
        defaultValue="submit"
        data-policy-group="visibility"
        data-policy-attribute="data-error-visibility"
      >
        <SelectTrigger id="policy-visibility" class="w-full">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {timings.map((timing) => (
            <SelectItem value={timing}>
              {timing[0]?.toUpperCase() + timing.slice(1)}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
  </div>

<Form
    class="grid gap-5"
    validationTiming="submit"
    revalidationTiming="change"
    errorVisibility="submit"
  >
    <FormErrorSummary aria-label="Account errors">
      <p class="font-medium">Review the highlighted fields.</p>
    </FormErrorSummary>
    <FieldGroup>
      <Field name="email">
        <FieldLabel>Email</FieldLabel>
        <FieldControl type="email" required placeholder="ada@example.com" />
        <FieldDescription>Try submitting an empty or incomplete address.</FieldDescription>
        <FieldError match="valueMissing">Enter your email address.</FieldError>
        <FieldError match="typeMismatch">Enter a valid email address.</FieldError>
      </Field>
      <Field
        name="workspace"
        validationTiming="change"
        revalidationTiming="blur"
        errorVisibility="change"
      >
        <FieldLabel>Override workspace</FieldLabel>
        <FieldControl required minlength="3" placeholder="acme" />
        <FieldDescription>
          Validates on change before submit, then only on blur afterward.
        </FieldDescription>
        <FieldError match="valueMissing">Choose a workspace name.</FieldError>
        <FieldError match="tooShort">Use at least three characters.</FieldError>
      </Field>
    </FieldGroup>

<div class="flex flex-wrap items-center gap-3">
      <Button type="submit">Create account</Button>
      <Button type="reset" variant="ghost">Reset</Button>
    </div>
  </Form>

<output class="text-muted-foreground mt-3 block text-sm" aria-live="polite">
    Before submit: submit. After submit: change. Errors: submit.
  </output>
</div>

demo?.querySelectorAll<HTMLElement>("[data-policy-attribute]").forEach((control) => {
    control.addEventListener("starwind:value-change", (event) => {
      const { value } = (event as CustomEvent<{ value: string | null }>).detail;
      const attribute = control.dataset.policyAttribute;
      if (value && attribute) {
        form?.setAttribute(attribute, value);
        renderPolicy();
      }
    });
  });

if (form) {
    form.addEventListener("submit", (event) => {
      event.preventDefault();
      renderPolicy(`Submitted ${String(new FormData(form).get("email") ?? "")}`);
    });
    form.addEventListener("reset", () => window.setTimeout(() => renderPolicy(), 0));
  }
</script>
```
  </div>
  <div slot="react">
```tsx
import { useState } from "react";
import type { FormValidationTiming } from "@starwind-ui/react/form";
import { Button } from "@/components/starwind/button";
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
} from "@/components/starwind/field";
import { Form, FormErrorSummary } from "@/components/starwind/form";
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/starwind/select";

const timings = ["submit", "blur", "change", "manual"] as const;

export function Example() {
  const [validationTiming, setValidationTiming] =
    useState<FormValidationTiming>("submit");
  const [revalidationTiming, setRevalidationTiming] =
    useState<FormValidationTiming>("change");
  const [errorVisibility, setErrorVisibility] =
    useState<FormValidationTiming>("submit");

return (
    <div className="w-full max-w-lg">
      <div className="mb-6 grid gap-4 sm:grid-cols-2">
        <TimingSelect
          id="policy-validation"
          label="Before submit"
          value={validationTiming}
          onValueChange={setValidationTiming}
        />
        <TimingSelect
          id="policy-revalidation"
          label="After submit"
          value={revalidationTiming}
          onValueChange={setRevalidationTiming}
        />
        <TimingSelect
          id="policy-visibility"
          label="Show errors"
          value={errorVisibility}
          onValueChange={setErrorVisibility}
        />
      </div>

<Form
        className="grid gap-5"
        validationTiming={validationTiming}
        revalidationTiming={revalidationTiming}
        errorVisibility={errorVisibility}
        onSubmit={(event) => event.preventDefault()}
      >
        <FormErrorSummary aria-label="Account errors">
          <p className="font-medium">Review the highlighted fields.</p>
        </FormErrorSummary>
        <FieldGroup>
          <Field name="email">
            <FieldLabel>Email</FieldLabel>
            <FieldControl type="email" required placeholder="ada@example.com" />
            <FieldDescription>Try submitting an empty or incomplete address.</FieldDescription>
            <FieldError match="valueMissing">Enter your email address.</FieldError>
            <FieldError match="typeMismatch">Enter a valid email address.</FieldError>
          </Field>
          <Field
            name="workspace"
            validationTiming="change"
            revalidationTiming="blur"
            errorVisibility="change"
          >
            <FieldLabel>Override workspace</FieldLabel>
            <FieldControl required minLength={3} placeholder="acme" />
            <FieldDescription>
              Validates on change before submit, then only on blur afterward.
            </FieldDescription>
            <FieldError match="tooShort">Use at least three characters.</FieldError>
          </Field>
        </FieldGroup>
        <div className="flex flex-wrap items-center gap-3">
          <Button type="submit">Create account</Button>
          <Button type="reset" variant="ghost">Reset</Button>
        </div>
      </Form>
      <output className="text-muted-foreground mt-3 block text-sm" aria-live="polite">
        Before submit: {validationTiming}. After submit: {revalidationTiming}. Errors:{" "}
        {errorVisibility}.
      </output>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Validation and error revelation

Validation computes errors; revelation determines whether those errors participate in visible
messages, descriptions, and the Form summary. A hidden error can set `aria-invalid`, but it does not
enter `aria-describedby` or `FormErrorSummary` until its Field is revealed.

Reveal eligibility is sticky. Becoming valid hides the current message but does not make the Field
“unrevealed”; a later error can appear immediately. Native reset, full `resetValidation()`, Field
removal, or `setErrorsVisible(false)` removes that eligibility.

<div class="not-content my-6 grid gap-3 sm:grid-cols-2">
<article class="border-border rounded-lg border p-4">
<h4 class="mb-2 font-mono text-sm">form.checkValidity()</h4>
<p class="text-muted-foreground text-sm">
  Runs native and synchronous custom validation without revealing errors, moving focus, or
  changing the Form phase.
</p>
</article>
<article class="border-border rounded-lg border p-4">
<h4 class="mb-2 font-mono text-sm">form.reportValidity()</h4>
<p class="text-muted-foreground text-sm">
  Runs synchronous validation, reveals every checked invalid Field, and focuses the first one
  without changing the Form phase.
</p>
</article>
<article class="border-border rounded-lg border p-4">
<h4 class="mb-2 font-medium">Submit attempt</h4>
<p class="text-muted-foreground text-sm">
  Runs native, synchronous custom, and managed async validation. It applies each Field's error
  policy, focuses the first invalid Field, and enters the after-submit phase.
</p>
</article>
<article class="border-border rounded-lg border p-4">
<h4 class="mb-2 font-mono text-sm">formApi.validate()</h4>
<p class="text-muted-foreground text-sm">
  Runs the complete validator pipeline with optional focus and revelation, returning one
  coherent async outcome without changing the Form phase.
</p>
</article>
</div>

## Solve a common problem

Choose the task that matches the form you are building. Only one complete recipe is shown at a
time; each recipe includes Astro and React code.

<DocsTabs defaultValue="custom" class="my-6">
<DocsTabsList class="grid grid-cols-2 gap-1 before:hidden sm:flex sm:gap-0 sm:before:block">
<DocsTabsTrigger value="custom">Custom rules</DocsTabsTrigger>
<DocsTabsTrigger value="async">Async checks</DocsTabsTrigger>
<DocsTabsTrigger value="server">Server errors</DocsTabsTrigger>
<DocsTabsTrigger value="schema">Zod</DocsTabsTrigger>
<DocsTabsTrigger value="manual">Wizard step</DocsTabsTrigger>
</DocsTabsList>

### Validate a wizard step

Retrieve the idempotent Form controller with `createForm(formElement)`. Use targeted names for a
wizard step or section, and opt into focus or unconditional revelation when the workflow calls for
it. Duplicate names target every matching Field; unknown names are ignored.

> **Info:** Submission always validates every registered Field. Manual timing disables matching interaction
validation; it does not allow an invalid Form to submit.

<div class="w-full max-w-lg" data-manual-validation>
  <Form
    validationTiming="manual"
    revalidationTiming="manual"
    errorVisibility="manual"
    class="grid gap-5"
  >
    <FormErrorSummary aria-label="Profile errors">
      <p class="font-medium">Review the highlighted fields.</p>
    </FormErrorSummary>

<FieldGroup>
      <Field name="email">
        <FieldLabel>Email</FieldLabel>
        <FieldControl type="email" required value="not-an-email" />
        <FieldDescription>
          Validation runs only when one of the buttons requests it.
        </FieldDescription>
        <FieldError match="valueMissing">Enter your email address.</FieldError>
        <FieldError match="typeMismatch">Enter a valid email address.</FieldError>
      </Field>

<Field name="displayName">
        <FieldLabel>Display name</FieldLabel>
        <FieldControl required minlength="3" value="Ada" />
        <FieldError match="valueMissing">Enter a display name.</FieldError>
        <FieldError match="tooShort">Use at least three characters.</FieldError>
      </Field>
    </FieldGroup>

<div class="flex flex-wrap items-center gap-2">
      <Button type="button" size="sm" data-action="validate-all">Validate all</Button>
      <Button type="button" size="sm" variant="outline" data-action="validate-email">
        Validate email + focus
      </Button>
      <Button type="button" size="sm" variant="outline" data-action="hide">
        Hide errors
      </Button>
      <Button type="button" size="sm" variant="ghost" data-action="reset">
        Reset validation
      </Button>
    </div>
  </Form>

<output class="text-muted-foreground mt-3 block text-sm" aria-live="polite">
    Change the values, then run validation.
  </output>
</div>

const read = (value: FormValues[string] | null | undefined) =>
    Array.isArray(value) ? String(value[0] ?? "") : String(value ?? "");

const demo = document.querySelector<HTMLElement>("[data-manual-validation]");
  const form = demo?.querySelector<HTMLFormElement>("form");
  const output = demo?.querySelector<HTMLOutputElement>("output");

if (demo && form && output) {
    const formApi = createForm(form);

demo.querySelector('[data-action="validate-all"]')?.addEventListener("click", async () => {
      output.value = describeOutcome("Full validation", await formApi.validate());
    });

demo.querySelector('[data-action="validate-email"]')?.addEventListener("click", async () => {
      const outcome = await formApi.validate({
        names: ["email"],
        reveal: true,
        focus: true,
      });
      output.value = describeOutcome("Email validation", outcome);
    });

demo.querySelector('[data-action="hide"]')?.addEventListener("click", () => {
      formApi.setErrorsVisible(false);
      output.value = "Errors hidden without clearing their validation results.";
    });

demo.querySelector('[data-action="reset"]')?.addEventListener("click", () => {
      formApi.resetValidation();
      const values = new FormData(form);
      output.value =
        `Validation reset; values preserved: ${read(values.get("email"))}, ` +
        `${read(values.get("displayName"))}.`;
    });
  }
</script>
```
  </div>
  <div slot="react">
```tsx
import {
  createForm,
  type FormValidationOutcome,
  type FormValues,
} from "@starwind-ui/react/form";
import { useRef, useState } from "react";
import { Button } from "@/components/starwind/button";
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
} from "@/components/starwind/field";
import { Form, FormErrorSummary } from "@/components/starwind/form";

const read = (value: FormValues[string] | null | undefined) =>
  Array.isArray(value) ? String(value[0] ?? "") : String(value ?? "");

export function Example() {
  const formRef = useRef<HTMLFormElement>(null);
  const [result, setResult] = useState("Change the values, then run validation.");

const getFormApi = () => {
    const form = formRef.current;
    return form ? createForm(form) : null;
  };

return (
    <div className="w-full max-w-lg">
      <Form
        ref={formRef}
        className="grid gap-5"
        validationTiming="manual"
        revalidationTiming="manual"
        errorVisibility="manual"
      >
        <FormErrorSummary aria-label="Profile errors">
          <p className="font-medium">Review the highlighted fields.</p>
        </FormErrorSummary>

<FieldGroup>
          <Field name="email">
            <FieldLabel>Email</FieldLabel>
            <FieldControl type="email" required defaultValue="not-an-email" />
            <FieldDescription>
              Validation runs only when one of the buttons requests it.
            </FieldDescription>
            <FieldError match="valueMissing">Enter your email address.</FieldError>
            <FieldError match="typeMismatch">Enter a valid email address.</FieldError>
          </Field>

<Field name="displayName">
            <FieldLabel>Display name</FieldLabel>
            <FieldControl required minLength={3} defaultValue="Ada" />
            <FieldError match="valueMissing">Enter a display name.</FieldError>
            <FieldError match="tooShort">Use at least three characters.</FieldError>
          </Field>
        </FieldGroup>

<div className="flex flex-wrap items-center gap-2">
          <Button
            type="button"
            size="sm"
            onClick={async () => {
              const outcome = await getFormApi()?.validate();
              if (outcome) setResult(describeOutcome("Full validation", outcome));
            }}
          >
            Validate all
          </Button>
          <Button
            type="button"
            size="sm"
            variant="outline"
            onClick={async () => {
              const outcome = await getFormApi()?.validate({
                names: ["email"],
                reveal: true,
                focus: true,
              });
              if (outcome) setResult(describeOutcome("Email validation", outcome));
            }}
          >
            Validate email + focus
          </Button>
          <Button
            type="button"
            size="sm"
            variant="outline"
            onClick={() => {
              getFormApi()?.setErrorsVisible(false);
              setResult("Errors hidden without clearing their validation results.");
            }}
          >
            Hide errors
          </Button>
          <Button
            type="button"
            size="sm"
            variant="ghost"
            onClick={() => {
              getFormApi()?.resetValidation();
              const values = formRef.current
                ? new FormData(formRef.current)
                : new FormData();
              setResult(
                `Validation reset; values preserved: ${read(values.get("email"))}, ${read(values.get("displayName"))}.`,
              );
            }}
          >
            Reset validation
          </Button>
        </div>
      </Form>

<output
        className="text-muted-foreground mt-3 block text-sm"
        aria-live="polite"
      >
        {result}
      </output>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

`validate()` defaults to no focus. With no `reveal` option it applies each checked Field's
`errorVisibility` to the `manual` cause; `reveal: true` forces invalid checked Fields to show, while
`reveal: false` adds no new reveal eligibility. Starting newer validation, resetting intersecting
Fields, or destroying the Form aborts older work, which resolves with `status: "aborted"`.

`setErrorsVisible(true, names)` and `setErrorsVisible(false, names)` change presentation without
clearing errors or changing the Form phase. `resetValidation()` clears validation and reveal state
without resetting values or dirty/touched state; native `form.reset()` also restores native control
values and returns the Form to its before-submit phase.

</DocsTabsContent>

### Add custom rules

Add domain rules without replacing native constraints. Field validators handle one value, form
validators compare values, and the managed submit callback only runs after every rule passes.

Without a Runtime `onSubmit` option, Starwind blocks invalid submission and lets a valid native
submission continue. Supplying `onSubmit` to `createForm()` activates managed submission: Runtime
prevents the native submit, runs synchronous and configured async validators, then calls the handler
with `values`, registered `fields`, the `submitter`, and the original event. A JSX `onSubmit` prop is
an ordinary DOM callback and does not by itself activate the managed async path.

<div class="w-full max-w-lg" data-project-form>
  <Form
    validationTiming="blur"
    revalidationTiming="change"
    errorVisibility="blur"
    class="grid gap-5"
  >
    <FieldGroup>
      <Field name="workspace">
        <FieldLabel>Workspace slug</FieldLabel>
        <FieldControl required value="acme" />
        <FieldError match="valueMissing">Enter a workspace slug.</FieldError>
      </Field>
      <Field name="project">
        <FieldLabel>Project slug</FieldLabel>
        <FieldControl required value="acme" />
        <FieldDescription>Try “admin” or the workspace slug.</FieldDescription>
        <FieldError match="valueMissing">Enter a project slug.</FieldError>
        <FieldError match="customError" messageSource="validation">
          Choose a different project slug.
        </FieldError>
      </Field>
    </FieldGroup>
    <div class="flex flex-wrap items-center gap-3">
      <Button type="submit">Create project</Button>
      <Button type="reset" variant="ghost">Reset</Button>
    </div>
  </Form>
  <output
    class="text-muted-foreground mt-3 block text-sm whitespace-pre-wrap"
    aria-live="polite"
  >
    Submit to run the custom rules.
  </output>
</div>

const demo = document.querySelector<HTMLElement>("[data-project-form]");
  const form = demo?.querySelector<HTMLFormElement>("form");
  const output = demo?.querySelector<HTMLOutputElement>("output");
  const read = (value: FormValues[string] | null | undefined) =>
    Array.isArray(value) ? String(value[0] ?? "") : String(value ?? "");

if (form) {
    createForm(form, {
      fieldValidators: {
        project: (value) =>
          read(value).toLowerCase() === "admin"
            ? "The admin project slug is reserved."
            : null,
      },
      formValidators: (values) =>
        read(values.workspace) === read(values.project)
          ? { project: "Project slug must differ from the workspace slug." }
          : null,
      onSubmit: ({ values }) => {
        if (output) output.value = `Created ${read(values.workspace)}/${read(values.project)}`;
      },
    });

form.addEventListener("reset", () => {
      window.setTimeout(() => {
        if (output) output.value = "Submit to run the custom rules.";
      }, 0);
    });
  }
</script>
```
  </div>
  <div slot="react">
```tsx
import { createForm, type FormValues } from "@starwind-ui/react/form";
import { useEffect, useRef, useState } from "react";
import { Button } from "@/components/starwind/button";
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
} from "@/components/starwind/field";
import { Form } from "@/components/starwind/form";

const read = (value: FormValues[string] | null | undefined) =>
  Array.isArray(value) ? String(value[0] ?? "") : String(value ?? "");

export function Example() {
  const formRef = useRef<HTMLFormElement>(null);
  const [result, setResult] = useState("Submit to run the custom rules.");

useEffect(() => {
    const form = formRef.current;
    if (!form) return;

createForm(form, {
      fieldValidators: {
        project: (value) =>
          read(value).toLowerCase() === "admin"
            ? "The admin project slug is reserved."
            : null,
      },
      formValidators: (values) =>
        read(values.workspace) === read(values.project)
          ? { project: "Project slug must differ from the workspace slug." }
          : null,
      onSubmit: ({ values }) => {
        setResult(`Created ${read(values.workspace)}/${read(values.project)}`);
      },
    });
  }, []);

return (
    <div className="w-full max-w-lg">
      <Form
        ref={formRef}
        className="grid gap-5"
        validationTiming="blur"
        revalidationTiming="change"
        errorVisibility="blur"
        onReset={() => setResult("Submit to run the custom rules.")}
      >
        <FieldGroup>
          <Field name="workspace">
            <FieldLabel>Workspace slug</FieldLabel>
            <FieldControl required defaultValue="acme" />
            <FieldError match="valueMissing">Enter a workspace slug.</FieldError>
          </Field>
          <Field name="project">
            <FieldLabel>Project slug</FieldLabel>
            <FieldControl required defaultValue="acme" />
            <FieldDescription>Try “admin” or the workspace slug.</FieldDescription>
            <FieldError match="valueMissing">Enter a project slug.</FieldError>
            <FieldError match="customError" messageSource="validation">
              Choose a different project slug.
            </FieldError>
          </Field>
        </FieldGroup>
        <div className="flex flex-wrap items-center gap-3">
          <Button type="submit">Create project</Button>
          <Button type="reset" variant="ghost">Reset</Button>
        </div>
      </Form>
      <output
        className="text-muted-foreground mt-3 block text-sm whitespace-pre-wrap"
        aria-live="polite"
      >
        {result}
      </output>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

</DocsTabsContent>

### Check availability asynchronously

Async validators receive an `AbortSignal`, so stale checks can be cancelled as accepted values
change. This example uses the default submit-then-change lifecycle: submit once to check
availability, then accepted corrections run the debounced validator. Pending or failed validation
blocks managed submission.

<div class="w-full max-w-lg" data-handle-form>
  <Form
    validationTiming="submit"
    revalidationTiming="change"
    errorVisibility="submit"
    class="grid gap-5"
  >
    <Field name="handle">
      <FieldLabel>Team handle</FieldLabel>
      <FieldControl required autocomplete="off" placeholder="your-team" />
      <FieldDescription>
        Try “starwind”, “admin”, “taken”, or your own handle.
      </FieldDescription>
      <FieldError match="valueMissing">Enter a team handle.</FieldError>
      <FieldError match="customError" messageSource="validation">
        That handle is unavailable.
      </FieldError>
      <FieldValidity match="valid">Handle is available.</FieldValidity>
    </Field>
    <div class="flex flex-wrap items-center gap-3">
      <Button type="submit">Reserve handle</Button>
      <Button type="reset" variant="ghost">Reset</Button>
    </div>
  </Form>
  <output class="text-muted-foreground mt-3 block text-sm" aria-live="polite">
    Submit once to check availability; accepted changes then recheck it.
  </output>
</div>

const unavailable = new Set(["admin", "starwind", "taken"]);
  const demo = document.querySelector<HTMLElement>("[data-handle-form]");
  const form = demo?.querySelector<HTMLFormElement>("form");
  const output = demo?.querySelector<HTMLOutputElement>("output");

if (form) {
    createForm(form, {
      asyncFieldValidators: {
        handle: async (value, { signal }) => {
          const handle = String(value ?? "").trim().toLowerCase();
          if (!handle) return null;
          if (output) output.value = `Checking “${handle}”…`;

await new Promise((resolve) => window.setTimeout(resolve, 400));
          if (signal.aborted) return null;

form.addEventListener("reset", () => {
      window.setTimeout(() => {
        if (output) {
          output.value =
            "Submit once to check availability; accepted changes then recheck it.";
        }
      }, 0);
    });
  }
</script>
```
  </div>
  <div slot="react">
```tsx
import { createForm } from "@starwind-ui/react/form";
import { useEffect, useRef, useState } from "react";
import { Button } from "@/components/starwind/button";
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldLabel,
  FieldValidity,
} from "@/components/starwind/field";
import { Form } from "@/components/starwind/form";

const unavailable = new Set(["admin", "starwind", "taken"]);

export function Example() {
  const formRef = useRef<HTMLFormElement>(null);
  const [result, setResult] = useState(
    "Submit once to check availability; accepted changes then recheck it.",
  );

useEffect(() => {
    const form = formRef.current;
    if (!form) return;

createForm(form, {
      asyncFieldValidators: {
        handle: async (value, { signal }) => {
          const handle = String(value ?? "").trim().toLowerCase();
          if (!handle) return null;
          setResult(`Checking “${handle}”…`);

await new Promise((resolve) => window.setTimeout(resolve, 400));
          if (signal.aborted) return null;

return (
    <div className="w-full max-w-lg">
      <Form
        ref={formRef}
        className="grid gap-5"
        validationTiming="submit"
        revalidationTiming="change"
        errorVisibility="submit"
        onReset={() =>
          setResult(
            "Submit once to check availability; accepted changes then recheck it.",
          )
        }
      >
        <Field name="handle">
          <FieldLabel>Team handle</FieldLabel>
          <FieldControl required autoComplete="off" placeholder="your-team" />
          <FieldDescription>
            Try “starwind”, “admin”, “taken”, or your own handle.
          </FieldDescription>
          <FieldError match="valueMissing">Enter a team handle.</FieldError>
          <FieldError match="customError" messageSource="validation">
            That handle is unavailable.
          </FieldError>
          <FieldValidity match="valid">Handle is available.</FieldValidity>
        </Field>
        <div className="flex flex-wrap items-center gap-3">
          <Button type="submit">Reserve handle</Button>
          <Button type="reset" variant="ghost">Reset</Button>
        </div>
      </Form>
      <output className="text-muted-foreground mt-3 block text-sm" aria-live="polite">
        {result}
      </output>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

</DocsTabsContent>

### Show server and external errors

Use `setExternalErrors()` for server responses and other errors computed outside the current
validation run. External errors mark matching Fields invalid without entering the post-submit
phase or moving focus.

<div class="w-full max-w-lg" data-server-error-form>
  <Form class="grid gap-5">
    <FormErrorSummary aria-label="Account errors">
      <p class="font-medium">Review the highlighted fields.</p>
    </FormErrorSummary>
    <Field name="email">
      <FieldLabel>Email</FieldLabel>
      <FieldControl type="email" required value="ada@example.com" />
      <FieldDescription>Edit the email to clear the server error.</FieldDescription>
      <FieldError match="customError" messageSource="validation">
        That email is already registered.
      </FieldError>
    </Field>
    <div class="flex flex-wrap items-center gap-2">
      <Button type="button" size="sm" data-show-server-error>Show server error</Button>
      <Button type="button" size="sm" variant="ghost" data-clear-server-error>
        Clear server error
      </Button>
    </div>
  </Form>
  <output class="text-muted-foreground mt-3 block text-sm" aria-live="polite">
    Apply a simulated server response.
  </output>
</div>

form.querySelector("[data-show-server-error]")?.addEventListener("click", () => {
      formApi.setExternalErrors(errors, {
        clearOnChange: true,
        visibility: "immediate",
      });
      output.value = "Immediate server error shown. Edit the email to clear it.";
    });

form.querySelector("[data-clear-server-error]")?.addEventListener("click", () => {
      formApi.clearExternalErrors("email");
      output.value = "External email errors cleared.";
    });
  }
</script>
```
  </div>
  <div slot="react">
```tsx
import { createForm } from "@starwind-ui/react/form";
import { useEffect, useRef, useState } from "react";
import { Button } from "@/components/starwind/button";
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldLabel,
} from "@/components/starwind/field";
import { Form, FormErrorSummary } from "@/components/starwind/form";

const serverErrors = {
  email: {
    key: "customError" as const,
    message: "That email is already registered.",
    source: "server" as const,
  },
};

export function Example() {
  const formRef = useRef<HTMLFormElement>(null);
  const formApiRef = useRef<ReturnType<typeof createForm> | null>(null);
  const [result, setResult] = useState("Apply a simulated server response.");

useEffect(() => {
    if (formRef.current) {
      formApiRef.current = createForm(formRef.current);
    }
  }, []);

return (
    <div className="w-full max-w-lg">
      <Form ref={formRef} className="grid gap-5">
        <FormErrorSummary aria-label="Account errors">
          <p className="font-medium">Review the highlighted fields.</p>
        </FormErrorSummary>
        <Field name="email">
          <FieldLabel>Email</FieldLabel>
          <FieldControl type="email" required defaultValue="ada@example.com" />
          <FieldDescription>Edit the email to clear the server error.</FieldDescription>
          <FieldError match="customError" messageSource="validation">
            That email is already registered.
          </FieldError>
        </Field>
        <div className="flex flex-wrap items-center gap-2">
          <Button
            type="button"
            size="sm"
            onClick={() => {
              formApiRef.current?.setExternalErrors(serverErrors, {
                clearOnChange: true,
              });
              setResult("Immediate server error shown. Edit the email to clear it.");
            }}
          >
            Show server error
          </Button>
          <Button
            type="button"
            size="sm"
            variant="ghost"
            onClick={() => {
              formApiRef.current?.clearExternalErrors("email");
              setResult("External email errors cleared.");
            }}
          >
            Clear server error
          </Button>
        </div>
      </Form>
      <output className="text-muted-foreground mt-3 block text-sm" aria-live="polite">
        {result}
      </output>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

`visibility` defaults to `immediate`. Use `visibility: "policy"` to store the error while preserving
the Field's current reveal eligibility; a later matching policy event can reveal it.
`clearOnChange` clears the matching external error on the next accepted semantic change.

Native reset clears external errors by default. Configure
`createForm(form, { externalErrorsOnReset: "preserve" })` to retain them, or override one validation
reset with `resetValidation({ externalErrors: "clear" | "preserve" })`. Preserved external errors
keep their prior reveal eligibility while unrelated reveal state is cleared.

</DocsTabsContent>

### Validate with Zod

Starwind does not require a schema library. A small parser adapter maps Zod issues to matching
fields, then `createFormSchemaValidator` runs that parser through the same validation and submission
pipeline. Install Zod in your app before using this example.

```bash
pnpm add zod
```

<div class="w-full max-w-lg" data-zod-form>
  <Form class="grid gap-5">
    <FormErrorSummary aria-label="Project errors">
      <p class="font-medium">Review the project details.</p>
    </FormErrorSummary>
    <FieldGroup>
      <Field name="workEmail">
        <FieldLabel>Work email</FieldLabel>
        <FieldControl type="email" value="ada@personal.test" />
        <FieldDescription>Use an @example.com address.</FieldDescription>
        <FieldError match="customError" messageSource="validation">
          Enter a valid work email.
        </FieldError>
      </Field>
      <Field name="projectKey">
        <FieldLabel>Project key</FieldLabel>
        <FieldControl value="sw" />
        <FieldDescription>
          Use four or more lowercase letters, numbers, or dashes.
        </FieldDescription>
        <FieldError match="customError" messageSource="validation">
          Enter a valid project key.
        </FieldError>
      </Field>
    </FieldGroup>
    <div class="flex flex-wrap items-center gap-3">
      <Button type="submit">Create project</Button>
      <Button type="reset" variant="ghost">Reset</Button>
    </div>
  </Form>
  <output class="text-muted-foreground mt-3 block text-sm" aria-live="polite">
    Submit to validate with Zod.
  </output>
</div>

const schema = z.object({
    workEmail: z
      .email({ error: "Enter a valid email address." })
      .refine((value) => value.endsWith("@example.com"), {
        error: "Use your @example.com work email.",
      }),
    projectKey: z
      .string()
      .min(4, { error: "Use at least four characters." })
      .regex(/^[a-z0-9-]+$/, { error: "Use lowercase letters, numbers, or dashes." }),
  });

form.addEventListener("reset", () => {
      window.setTimeout(() => {
        if (output) output.value = "Submit to validate with Zod.";
      }, 0);
    });
  }
</script>
```
  </div>
  <div slot="react">
```tsx
import { z } from "zod";
import {
  createForm,
  createFormSchemaValidator,
  type FormSchemaResult,
  type FormValues,
} from "@starwind-ui/react/form";
import { useEffect, useRef, useState } from "react";
import { Button } from "@/components/starwind/button";
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
} from "@/components/starwind/field";
import { Form, FormErrorSummary } from "@/components/starwind/form";

const schema = z.object({
  workEmail: z
    .email({ error: "Enter a valid email address." })
    .refine((value) => value.endsWith("@example.com"), {
      error: "Use your @example.com work email.",
    }),
  projectKey: z
    .string()
    .min(4, { error: "Use at least four characters." })
    .regex(/^[a-z0-9-]+$/, { error: "Use lowercase letters, numbers, or dashes." }),
});

const read = (value: FormValues[string] | undefined) =>
  Array.isArray(value) ? String(value[0] ?? "") : String(value ?? "");

export function Example() {
  const formRef = useRef<HTMLFormElement>(null);
  const [result, setResult] = useState("Submit to validate with Zod.");

useEffect(() => {
    const form = formRef.current;
    if (!form) return;
    createForm(form, {
      formValidators: createFormSchemaValidator(parse),
      onSubmit: ({ values }) => setResult(`Created ${read(values.projectKey)}`),
    });
  }, []);

return (
    <div className="w-full max-w-lg">
      <Form
        ref={formRef}
        className="grid gap-5"
        onReset={() => setResult("Submit to validate with Zod.")}
      >
        <FormErrorSummary aria-label="Project errors">
          <p className="font-medium">Review the project details.</p>
        </FormErrorSummary>
        <FieldGroup>
          <Field name="workEmail">
            <FieldLabel>Work email</FieldLabel>
            <FieldControl type="email" defaultValue="ada@personal.test" />
            <FieldDescription>Use an @example.com address.</FieldDescription>
            <FieldError match="customError" messageSource="validation">
              Enter a valid work email.
            </FieldError>
          </Field>
          <Field name="projectKey">
            <FieldLabel>Project key</FieldLabel>
            <FieldControl defaultValue="sw" />
            <FieldDescription>
              Use four or more lowercase letters, numbers, or dashes.
            </FieldDescription>
            <FieldError match="customError" messageSource="validation">
              Enter a valid project key.
            </FieldError>
          </Field>
        </FieldGroup>
        <div className="flex flex-wrap items-center gap-3">
          <Button type="submit">Create project</Button>
          <Button type="reset" variant="ghost">Reset</Button>
        </div>
      </Form>
      <output className="text-muted-foreground mt-3 block text-sm" aria-live="polite">
        {result}
      </output>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

</DocsTabsContent>
</DocsTabs>

## Accessibility

Validation and presentation stay synchronized across native and Runtime-backed controls:

- Invalid checked Fields receive `aria-invalid` even when their messages are still hidden.
- Only revealed errors participate in `aria-describedby` and `FormErrorSummary`.
- `reportValidity()`, blocked submission, and `validate({ focus: true })` focus the first applicable
invalid Field in DOM order; `checkValidity()` and default `validate()` do not move focus.
- Summary entries remain in DOM order and keep duplicate-name Field roots distinct. Activating an
entry focuses its Field control.
- Focus moving among descendants of one composite Field does not count as blur.

Keep `FormErrorSummary` explicit so its placement, heading, and surrounding instructions match the
product. Field-level timing props can override the owning Form independently, but omitting them
keeps the policy easier to understand and maintain.

## API Reference
### Form
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `errorVisibility` | `"blur" \| "change" \| "manual" \| "submit"` | No | `"submit"` | Primitive override | Selects whether semantic change, blur, submit, or manual validation reveals errors; defaults to submit. |
| `revalidationTiming` | `"blur" \| "change" \| "manual" \| "submit"` | No | `"change"` | Primitive override | After a Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; defaults to change. |
| `validationTiming` | `"blur" \| "change" \| "manual" \| "submit"` | No | `"submit"` | Primitive override | Selects semantic change, blur, submit, or manual validation before a Form submission attempt; defaults to submit. |
- Inherits form attributes.

### FormErrorSummary
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Form Primitive](/docs/primitives/form/)
- Runtime factory: [`createForm`](/docs/runtime/#create-form) from `@starwind-ui/runtime/form`

## Changelog

### v1.0.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v1.0.0

- Added Runtime-backed native form coordination and validation timing.
- See the [Form Primitive](/docs/primitives/form/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/hover-card/](https://starwind.dev/docs/components/hover-card/) · [Markdown](https://starwind.dev/docs/components/hover-card.md)

# Hover Card

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Avatar, AvatarFallback, AvatarImage } from "@/components/starwind/avatar";
import { Button } from "@/components/starwind/button";
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/starwind/hover-card";
---

<HoverCard>
  <HoverCardTrigger asChild>
    <Button variant="outline">@starwind</Button>
  </HoverCardTrigger>
  <HoverCardContent class="w-80" align="start">
    <div class="flex justify-between gap-4">
      <Avatar class="shrink-0">
        <AvatarImage src="https://i.pravatar.cc/150?u=starwind" alt="Starwind UI" />
        <AvatarFallback>SW</AvatarFallback>
      </Avatar>
      <div class="space-y-1">
        <h4 class="text-sm font-semibold">Starwind UI</h4>
        <p class="text-muted-foreground text-sm">
          Accessible Astro components styled with Tailwind CSS.
        </p>
        <span class="text-muted-foreground block pt-2 text-xs">Built for Astro developers</span>
      </div>
    </div>
  </HoverCardContent>
</HoverCard>
```
  </div>
  <div slot="react">
```tsx
import { Avatar, AvatarFallback, AvatarImage } from "@/components/starwind/avatar";
import { Button } from "@/components/starwind/button";
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/starwind/hover-card";

export function Example() {
  return (
    <HoverCard>
      <HoverCardTrigger asChild>
        <Button variant="outline">@starwind</Button>
      </HoverCardTrigger>
      <HoverCardContent className="w-80" align="start">
        <div className="flex justify-between gap-4">
          <Avatar className="shrink-0">
            <AvatarImage src="https://i.pravatar.cc/150?u=starwind" alt="Starwind UI" />
            <AvatarFallback>SW</AvatarFallback>
          </Avatar>
          <div className="space-y-1">
            <h4 className="text-sm font-semibold">Starwind UI</h4>
            <p className="text-muted-foreground text-sm">
              Accessible Astro components styled with Tailwind CSS.
            </p>
            <span className="text-muted-foreground block pt-2 text-xs">Built for Astro developers</span>
          </div>
        </div>
      </HoverCardContent>
    </HoverCard>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add hover-card
```

## Usage

### General Notes

Hover Card shows additional context when a trigger is hovered or focused, without forcing a click.

The essential components are `HoverCard`, `HoverCardTrigger`, and `HoverCardContent`.

### Profile Preview

Use `asChild` on the trigger when you want to reuse an existing interactive component like `Button`.

<div class="flex flex-wrap items-center gap-4">
  <HoverCard>
    <HoverCardTrigger asChild>
      <Button variant="outline">@starwind</Button>
    </HoverCardTrigger>
    <HoverCardContent align="start" class="w-80">
      <div class="flex justify-between gap-4">
        <Avatar class="shrink-0">
          <AvatarImage src="https://i.pravatar.cc/150?u=starwind" alt="Starwind UI" />
          <AvatarFallback>SW</AvatarFallback>
        </Avatar>
        <div class="space-y-1">
          <h4 class="text-sm font-semibold">Starwind UI</h4>
          <p class="text-muted-foreground text-sm">
            Accessible Astro components styled with Tailwind CSS.
          </p>
          <div class="flex items-center pt-2">
            <span class="text-muted-foreground text-xs">Built for Astro developers</span>
          </div>
        </div>
      </div>
    </HoverCardContent>
  </HoverCard>

<HoverCard openDelay={200} closeDelay={200}>
    <HoverCardTrigger asChild>
      <Button href="https://astro.build" variant="ghost">Astro</Button>
    </HoverCardTrigger>
    <HoverCardContent side="right" align="start" class="w-80">
      <div class="space-y-2">
        <h4 class="text-sm font-semibold">Astro</h4>
        <p class="text-muted-foreground text-sm">
          A web framework for content-driven sites with fast-by-default performance.
        </p>
      </div>
    </HoverCardContent>
  </HoverCard>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Avatar, AvatarFallback, AvatarImage } from "@/components/starwind/avatar";
import { Button } from "@/components/starwind/button";
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/starwind/hover-card";

export function Example() {
  return (
    <>
      <div className="flex flex-wrap items-center gap-4">
        <HoverCard>
          <HoverCardTrigger asChild>
            <Button variant="outline">@starwind</Button>
          </HoverCardTrigger>
          <HoverCardContent align="start" className="w-80">
            <div className="flex justify-between gap-4">
              <Avatar className="shrink-0">
                <AvatarImage src="https://i.pravatar.cc/150?u=starwind" alt="Starwind UI" />
                <AvatarFallback>SW</AvatarFallback>
              </Avatar>
              <div className="space-y-1">
                <h4 className="text-sm font-semibold">Starwind UI</h4>
                <p className="text-muted-foreground text-sm">
                  Accessible Astro components styled with Tailwind CSS.
                </p>
                <div className="flex items-center pt-2">
                  <span className="text-muted-foreground text-xs">Built for Astro developers</span>
                </div>
              </div>
            </div>
          </HoverCardContent>
        </HoverCard>

<HoverCard openDelay={200} closeDelay={200}>
          <HoverCardTrigger asChild>
            <Button href="https://astro.build" variant="ghost">Astro</Button>
          </HoverCardTrigger>
          <HoverCardContent side="right" align="start" className="w-80">
            <div className="space-y-2">
              <h4 className="text-sm font-semibold">Astro</h4>
              <p className="text-muted-foreground text-sm">
                A web framework for content-driven sites with fast-by-default performance.
              </p>
            </div>
          </HoverCardContent>
        </HoverCard>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Side and Alignment

Use `side`, `align`, and `sideOffset` on `HoverCardContent` to control placement.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/starwind/hover-card";
---

<div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
  <HoverCard openDelay={150}>
    <HoverCardTrigger asChild>
      <Button variant="outline" class="w-full">Top</Button>
    </HoverCardTrigger>
    <HoverCardContent side="top" sideOffset={8}>Appears above the trigger.</HoverCardContent>
  </HoverCard>

<HoverCard openDelay={150}>
    <HoverCardTrigger asChild>
      <Button variant="outline" class="w-full">Right</Button>
    </HoverCardTrigger>
    <HoverCardContent side="right" align="start" sideOffset={8}>
      Appears to the right and aligns to the start.
    </HoverCardContent>
  </HoverCard>

<HoverCard openDelay={150}>
    <HoverCardTrigger asChild>
      <Button variant="outline" class="w-full">Bottom</Button>
    </HoverCardTrigger>
    <HoverCardContent side="bottom" align="end" sideOffset={8}>
      Appears below and aligns to the end.
    </HoverCardContent>
  </HoverCard>

<HoverCard openDelay={150}>
    <HoverCardTrigger asChild>
      <Button variant="outline" class="w-full">Left</Button>
    </HoverCardTrigger>
    <HoverCardContent side="left" sideOffset={8}>Appears to the left.</HoverCardContent>
  </HoverCard>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/starwind/hover-card";

export function Example() {
  return (
    <>
      <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
        <HoverCard openDelay={150}>
          <HoverCardTrigger asChild>
            <Button variant="outline" className="w-full">Top</Button>
          </HoverCardTrigger>
          <HoverCardContent side="top" sideOffset={8}>Appears above the trigger.</HoverCardContent>
        </HoverCard>

<HoverCard openDelay={150}>
          <HoverCardTrigger asChild>
            <Button variant="outline" className="w-full">Right</Button>
          </HoverCardTrigger>
          <HoverCardContent side="right" align="start" sideOffset={8}>
            Appears to the right and aligns to the start.
          </HoverCardContent>
        </HoverCard>

<HoverCard openDelay={150}>
          <HoverCardTrigger asChild>
            <Button variant="outline" className="w-full">Bottom</Button>
          </HoverCardTrigger>
          <HoverCardContent side="bottom" align="end" sideOffset={8}>
            Appears below and aligns to the end.
          </HoverCardContent>
        </HoverCard>

<HoverCard openDelay={150}>
          <HoverCardTrigger asChild>
            <Button variant="outline" className="w-full">Left</Button>
          </HoverCardTrigger>
          <HoverCardContent side="left" sideOffset={8}>Appears to the left.</HoverCardContent>
        </HoverCard>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Non-hoverable Content

By default, moving the pointer from trigger to content keeps the card open. Set `disableHoverableContent` to close immediately when leaving the trigger.

<HoverCard>
  <HoverCardTrigger asChild>
    <Button variant="outline">Hoverable content (default)</Button>
  </HoverCardTrigger>
  <HoverCardContent class="max-w-[220px]">
    You can move your pointer into this card without closing it.
  </HoverCardContent>
</HoverCard>

<HoverCard disableHoverableContent>
  <HoverCardTrigger asChild>
    <Button variant="outline">Trigger-only hover</Button>
  </HoverCardTrigger>
  <HoverCardContent class="max-w-[220px]">
    This card closes when the pointer leaves the trigger.
  </HoverCardContent>
</HoverCard>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/starwind/hover-card";

export function Example() {
  return (
    <>
      <HoverCard>
        <HoverCardTrigger asChild>
          <Button variant="outline">Hoverable content (default)</Button>
        </HoverCardTrigger>
        <HoverCardContent className="max-w-[220px]">
          You can move your pointer into this card without closing it.
        </HoverCardContent>
      </HoverCard>

<HoverCard disableHoverableContent>
        <HoverCardTrigger asChild>
          <Button variant="outline">Trigger-only hover</Button>
        </HoverCardTrigger>
        <HoverCardContent className="max-w-[220px]">
          This card closes when the pointer leaves the trigger.
        </HoverCardContent>
      </HoverCard>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### HoverCard
- Inherits div attributes.

### HoverCardTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Primitive override | Merges the component behavior and props into its child element. |
| `closeDelay` | `number` | No | - | Primitive override | Sets the delay in milliseconds before closing. |
| `openDelay` | `number` | No | - | Primitive override | Sets the delay in milliseconds before opening. |
- Inherits a attributes.

### HoverCardContent
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `positionerClass` | `string` | No | - | Wrapper prop | Adds classes to the generated floating positioner element. |
| `sideOffset` | `number` | No | `4` | Primitive override | Sets the distance in pixels between floating content and its anchor. |
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Preview Card Primitive](/docs/primitives/preview-card/)
- Runtime factory: [`createPreviewCard`](/docs/runtime/#create-preview-card) from `@starwind-ui/runtime/preview-card`

## Changelog

### v2.1.0

- Added `positionerClass` to `HoverCardContent` so the floating positioner can be styled directly.
- Moved the default stacking level from the content to the positioner.

### v2.0.2

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.0

- Rebuilt Hover Card on Starwind Runtime for hover and focus state, floating placement, and dismissal.
- See the [Preview Card Primitive](/docs/primitives/preview-card/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/image/](https://starwind.dev/docs/components/image/) · [Markdown](https://starwind.dev/docs/components/image.md)

# Image

<div data-framework-availability-notice>
> **Info:** Starwind's `Image` component wraps Astro's image optimization APIs and is only available in Astro. In React, use your framework's image component, or a native `<img>` when framework-level optimization isn't needed.
</div>

```astro
---
import pricingImage from "@/assets/images/pricing-9.jpg";
import { Image } from "@/components/starwind/image";
---

<Image src={pricingImage} alt="Pricing illustration" class="rounded-lg" />
```

## Installation

```bash
npx starwind@latest add image
```

## Usage

### General Notes

The `Image` component is a thin wrapper around Astro's built-in `<Image />` component. It provides:

- **Automatic size inference**: `inferSize` is enabled by default, so you don't need to specify width and height for remote images
- **Responsive defaults**: Images are set to `w-full h-auto` for responsive behavior
- **Optimized output**: Leverages Astro's image optimization pipeline

### Remote URL

You can use remote URLs directly. For deterministic builds, provide dimensions and disable remote
size inference.

```astro
---
import { Image } from "@/components/starwind/image";
---

<Image
  src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800&dpr=2&q=80"
  alt="Sleek gray design"
  width={800}
  height={533}
  inferSize={false}
  class="rounded-lg"
/>
```

## API Reference
### Image
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `inferSize` | `boolean` | No | `true` | Wrapper prop | Infers missing image dimensions from the source when possible. |
- Inherits Partial<import("astro/types").ComponentProps<typeof AstroImage>>.

## Changelog

### v1.1.0

- Moved Image to contract-generated Astro registry output while preserving its `astro:assets` integration; Image remains Astro-only.

### v1.0.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.13.0

---

Source: [https://starwind.dev/docs/components/input/](https://starwind.dev/docs/components/input/) · [Markdown](https://starwind.dev/docs/components/input.md)

# Input

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Input } from "@/components/starwind/input";
---

<Input placeholder="Type something..." />
```
  </div>
  <div slot="react">
```tsx
import { Input } from "@/components/starwind/input";

export function Example() {
  return (
    <Input placeholder="Type something..." />
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add input
```

## Usage

### size

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Input } from "@/components/starwind/input";
---

<Input size="sm" placeholder="Small input" />
<Input size="md" placeholder="Medium input" />
<Input size="lg" placeholder="Large input" />
```
  </div>
  <div slot="react">
```tsx
import { Input } from "@/components/starwind/input";

export function Example() {
  return (
    <>
      <Input size="sm" placeholder="Small input" />
      <Input size="md" placeholder="Medium input" />
      <Input size="lg" placeholder="Large input" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### disabled

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Input } from "@/components/starwind/input";
---

<Input disabled placeholder="Disabled input" />
<Input disabled value="Disabled with value" />
```
  </div>
  <div slot="react">
```tsx
import { Input } from "@/components/starwind/input";

export function Example() {
  return (
    <>
      <Input disabled placeholder="Disabled input" />
      <Input disabled value="Disabled with value" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### with type

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Input } from "@/components/starwind/input";
---

<Input type="email" placeholder="Email input" />
<Input type="password" placeholder="Password input" />
<Input type="number" placeholder="Number input" />
<Input type="file" />
```
  </div>
  <div slot="react">
```tsx
import { Input } from "@/components/starwind/input";

export function Example() {
  return (
    <>
      <Input type="email" placeholder="Email input" />
      <Input type="password" placeholder="Password input" />
      <Input type="number" placeholder="Number input" />
      <Input type="file" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Input
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultValue` | `string \| number \| string[]` | No | - | Primitive override | Sets the initial value when the component is uncontrolled. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `value` | `string \| number \| string[]` | No | - | Primitive override | Controls or identifies the component value. |
- Inherits input attributes. Omits `children`, `defaultValue`, `size`, and `value`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Input Primitive](/docs/primitives/input/)
- Runtime factory: [`createInput`](/docs/runtime/#create-input) from `@starwind-ui/runtime/input`

## Changelog

### v2.0.1

- Updated React Runtime state synchronization so canceled proposals stay uncommitted and accepted changes remain aligned.

### v2.0.0

- Rebuilt Input on Starwind Runtime for value synchronization while retaining native input attributes.
- See the [Input Primitive](/docs/primitives/input/) for the underlying unstyled anatomy and behavior API.

### v1.3.3

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.3.1

- add `aria-invalid` styling

### v1.3.0

- style and focus state updates

### v1.2.0

- Add `data-slot` attribute to enable global styling updates

### v1.1.1

- Add eslint disable comment for allowing the label to not have an associated control (this is user responsibility)
- 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.

---

Source: [https://starwind.dev/docs/components/input-group/](https://starwind.dev/docs/components/input-group/) · [Markdown](https://starwind.dev/docs/components/input-group.md)

# Input Group

InputGroup,
InputGroupAddon,
InputGroupButton,
InputGroupInput,
InputGroupText,
InputGroupTextarea,
} from "@/components/starwind/input-group";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@/components/starwind/input-group";
import Search from "@tabler/icons/outline/search.svg";
---

<InputGroup>
  <InputGroupInput aria-label="Search" placeholder="Search..." />
  <InputGroupAddon>
    <Search />
  </InputGroupAddon>
</InputGroup>
```
  </div>
  <div slot="react">
```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@/components/starwind/input-group";
import { IconSearch } from "@tabler/icons-react";

export function Example() {
  return (
    <InputGroup>
      <InputGroupInput aria-label="Search" placeholder="Search..." />
      <InputGroupAddon>
        <IconSearch />
      </InputGroupAddon>
    </InputGroup>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add input-group
```

## Usage

### General Notes

The essential components are `InputGroup`, `InputGroupAddon`, and either `InputGroupInput` or `InputGroupTextarea`.

`InputGroupText` and `InputGroupButton` are helper components for metadata and actions. Addons are
presentational; associate a field with an external `Label` or an `aria-label` on the control.

Keep `InputGroupAddon` after `InputGroupInput` or `InputGroupTextarea` in the DOM. Use `align` to
control visual placement.

### Align

#### inline-start

Use `align="inline-start"` to place content at the start of the field. This is the default alignment.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/starwind/input-group";
import Search from "@tabler/icons/outline/search.svg";
---

<InputGroup>
  <InputGroupInput placeholder="Search..." />
  <InputGroupAddon align="inline-start">
    <Search />
  </InputGroupAddon>
</InputGroup>
```
  </div>
  <div slot="react">
```tsx
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/starwind/input-group";
import { IconSearch as Search } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <InputGroup>
        <InputGroupInput placeholder="Search..." />
        <InputGroupAddon align="inline-start">
          <Search />
        </InputGroupAddon>
      </InputGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

#### inline-end

Use `align="inline-end"` to place content at the end of the field.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/starwind/input-group";
import InfoCircle from "@tabler/icons/outline/info-circle.svg";
---

<InputGroup>
  <InputGroupInput type="password" placeholder="Enter password" />
  <InputGroupAddon align="inline-end">
    <InfoCircle />
  </InputGroupAddon>
</InputGroup>
```
  </div>
  <div slot="react">
```tsx
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/starwind/input-group";
import { IconInfoCircle as InfoCircle } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <InputGroup>
        <InputGroupInput type="password" placeholder="Enter password" />
        <InputGroupAddon align="inline-end">
          <InfoCircle />
        </InputGroupAddon>
      </InputGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

#### block-start

Use `align="block-start"` to place a header row above the control.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/starwind/input-group";
import Code from "@tabler/icons/outline/code.svg";
import Copy from "@tabler/icons/outline/copy.svg";
---

<InputGroup>
    <InputGroupTextarea class="font-mono text-sm" placeholder="console.log('Hello, world!');" />
    <InputGroupAddon align="block-start" class="border-b">
      <Code />
      <InputGroupText class="font-mono">script.js</InputGroupText>
      <InputGroupButton size="icon-sm" class="ml-auto" aria-label="Copy code">
        <Copy />
      </InputGroupButton>
    </InputGroupAddon>
  </InputGroup>
</div>
```
  </div>
  <div slot="react">
```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/starwind/input-group";
import { IconCode as Code } from "@tabler/icons-react";
import { IconCopy as Copy } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <div className="grid w-full max-w-sm gap-4">
        <InputGroup>
          <InputGroupInput placeholder="Enter your name" />
          <InputGroupAddon align="block-start">
            <InputGroupText>Full Name</InputGroupText>
          </InputGroupAddon>
        </InputGroup>

<InputGroup>
          <InputGroupTextarea className="font-mono text-sm" placeholder="console.log('Hello, world!');" />
          <InputGroupAddon align="block-start" className="border-b">
            <Code />
            <InputGroupText className="font-mono">script.js</InputGroupText>
            <InputGroupButton size="icon-sm" className="ml-auto" aria-label="Copy code">
              <Copy />
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

#### block-end

Use `align="block-end"` to place a footer row below the control.

<InputGroup>
    <InputGroupTextarea placeholder="Write a comment..." />
    <InputGroupAddon align="block-end">
      <InputGroupText>0/280</InputGroupText>
      <InputGroupButton variant="default" size="sm" class="ml-auto">Post</InputGroupButton>
    </InputGroupAddon>
  </InputGroup>
</div>
```
  </div>
  <div slot="react">
```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/starwind/input-group";

export function Example() {
  return (
    <>
      <div className="grid w-full max-w-sm gap-4">
        <InputGroup>
          <InputGroupInput placeholder="Enter amount" />
          <InputGroupAddon align="block-end">
            <InputGroupText>USD</InputGroupText>
          </InputGroupAddon>
        </InputGroup>

### Examples

#### Icon

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/starwind/input-group";
import CircleCheck from "@tabler/icons/outline/circle-check.svg";
import CreditCard from "@tabler/icons/outline/credit-card.svg";
import InfoCircle from "@tabler/icons/outline/info-circle.svg";
import Mail from "@tabler/icons/outline/mail.svg";
import Search from "@tabler/icons/outline/search.svg";
import Star from "@tabler/icons/outline/star.svg";
---

<InputGroup>
    <InputGroupInput placeholder="Favorites" />
    <InputGroupAddon align="inline-end">
      <Star />
      <InfoCircle />
    </InputGroupAddon>
  </InputGroup>
</div>
```
  </div>
  <div slot="react">
```tsx
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/starwind/input-group";
import { IconCircleCheck as CircleCheck } from "@tabler/icons-react";
import { IconCreditCard as CreditCard } from "@tabler/icons-react";
import { IconInfoCircle as InfoCircle } from "@tabler/icons-react";
import { IconMail as Mail } from "@tabler/icons-react";
import { IconSearch as Search } from "@tabler/icons-react";
import { IconStar as Star } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <div className="grid w-full max-w-sm gap-6">
        <InputGroup>
          <InputGroupInput placeholder="Search..." />
          <InputGroupAddon>
            <Search />
          </InputGroupAddon>
        </InputGroup>

#### Text

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/starwind/input-group";
---

<InputGroup>
    <InputGroupInput placeholder="example" class="!pl-0.5" />
    <InputGroupAddon align="inline-start">
      <InputGroupText>https://</InputGroupText>
    </InputGroupAddon>
    <InputGroupAddon align="inline-end">
      <InputGroupText>.com</InputGroupText>
    </InputGroupAddon>
  </InputGroup>

<InputGroup>
    <InputGroupInput placeholder="Enter your username" />
    <InputGroupAddon align="inline-end">
      <InputGroupText>@company.com</InputGroupText>
    </InputGroupAddon>
  </InputGroup>

<InputGroup>
    <InputGroupTextarea placeholder="Enter your message" />
    <InputGroupAddon align="block-end">
      <InputGroupText class="text-xs">120 characters left</InputGroupText>
    </InputGroupAddon>
  </InputGroup>
</div>
```
  </div>
  <div slot="react">
```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/starwind/input-group";

export function Example() {
  return (
    <>
      <div className="grid w-full max-w-sm gap-6">
        <InputGroup>
          <InputGroupInput placeholder="0.00" />
          <InputGroupAddon align="inline-start">
            <InputGroupText>$</InputGroupText>
          </InputGroupAddon>
          <InputGroupAddon align="inline-end">
            <InputGroupText>USD</InputGroupText>
          </InputGroupAddon>
        </InputGroup>

<InputGroup>
          <InputGroupInput placeholder="example" className="!pl-0.5" />
          <InputGroupAddon align="inline-start">
            <InputGroupText>https://</InputGroupText>
          </InputGroupAddon>
          <InputGroupAddon align="inline-end">
            <InputGroupText>.com</InputGroupText>
          </InputGroupAddon>
        </InputGroup>

<InputGroup>
          <InputGroupInput placeholder="Enter your username" />
          <InputGroupAddon align="inline-end">
            <InputGroupText>@company.com</InputGroupText>
          </InputGroupAddon>
        </InputGroup>

<InputGroup>
          <InputGroupTextarea placeholder="Enter your message" />
          <InputGroupAddon align="block-end">
            <InputGroupText className="text-xs">120 characters left</InputGroupText>
          </InputGroupAddon>
        </InputGroup>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

#### Button

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
} from "@/components/starwind/input-group";
import Copy from "@tabler/icons/outline/copy.svg";
import InfoCircle from "@tabler/icons/outline/info-circle.svg";
import Star from "@tabler/icons/outline/star.svg";
---

<InputGroup class="[--radius:9999px]">
    <InputGroupInput placeholder="secure-site" />
    <InputGroupAddon align="inline-start">
      <InputGroupButton variant="secondary" size="icon-sm" aria-label="Info">
        <InfoCircle />
      </InputGroupButton>
    </InputGroupAddon>
    <InputGroupAddon align="inline-start" class="pl-1.5">
      <InputGroupText>https://</InputGroupText>
    </InputGroupAddon>
    <InputGroupAddon align="inline-end">
      <InputGroupButton size="icon-sm" aria-label="Favorite">
        <Star />
      </InputGroupButton>
    </InputGroupAddon>
  </InputGroup>

<InputGroup>
    <InputGroupInput placeholder="Type to search..." />
    <InputGroupAddon align="inline-end">
      <InputGroupButton variant="secondary">Search</InputGroupButton>
    </InputGroupAddon>
  </InputGroup>
</div>
```
  </div>
  <div slot="react">
```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
} from "@/components/starwind/input-group";
import { IconCopy as Copy } from "@tabler/icons-react";
import { IconInfoCircle as InfoCircle } from "@tabler/icons-react";
import { IconStar as Star } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <div className="grid w-full max-w-sm gap-6">
        <InputGroup>
          <InputGroupInput placeholder="https://starwind.dev" readOnly />
          <InputGroupAddon align="inline-end">
            <InputGroupButton aria-label="Copy" title="Copy" size="icon-sm">
              <Copy />
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>

<InputGroup className="[--radius:9999px]">
          <InputGroupInput placeholder="secure-site" />
          <InputGroupAddon align="inline-start">
            <InputGroupButton variant="secondary" size="icon-sm" aria-label="Info">
              <InfoCircle />
            </InputGroupButton>
          </InputGroupAddon>
          <InputGroupAddon align="inline-start" className="pl-1.5">
            <InputGroupText>https://</InputGroupText>
          </InputGroupAddon>
          <InputGroupAddon align="inline-end">
            <InputGroupButton size="icon-sm" aria-label="Favorite">
              <Star />
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>

#### Kbd

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/starwind/input-group";
import { Kbd } from "@/components/starwind/kbd";
import Search from "@tabler/icons/outline/search.svg";
---

<InputGroup>
  <InputGroupInput placeholder="Search..." />
  <InputGroupAddon>
    <Search />
  </InputGroupAddon>
  <InputGroupAddon align="inline-end">
    <Kbd>Ctrl+K</Kbd>
  </InputGroupAddon>
</InputGroup>
```
  </div>
  <div slot="react">
```tsx
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/starwind/input-group";
import { Kbd } from "@/components/starwind/kbd";
import { IconSearch as Search } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <InputGroup>
        <InputGroupInput placeholder="Search..." />
        <InputGroupAddon>
          <Search />
        </InputGroupAddon>
        <InputGroupAddon align="inline-end">
          <Kbd>Ctrl+K</Kbd>
        </InputGroupAddon>
      </InputGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

#### Dropdown

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Dropdown, DropdownContent, DropdownItem, DropdownTrigger } from "@/components/starwind/dropdown";
import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from "@/components/starwind/input-group";
import ChevronDown from "@tabler/icons/outline/chevron-down.svg";
---

<div class="grid w-full max-w-sm gap-4">
  <InputGroup>
    <InputGroupInput placeholder="Enter file name" />
    <InputGroupAddon align="inline-end">
      <Dropdown>
        <DropdownTrigger asChild>
          <InputGroupButton aria-label="More options" size="icon-sm">
            <ChevronDown />
          </InputGroupButton>
        </DropdownTrigger>
        <DropdownContent align="end">
          <DropdownItem>Settings</DropdownItem>
          <DropdownItem>Copy path</DropdownItem>
          <DropdownItem>Open location</DropdownItem>
        </DropdownContent>
      </Dropdown>
    </InputGroupAddon>
  </InputGroup>

<InputGroup class="[--radius:1rem]">
    <InputGroupInput placeholder="Enter search query" />
    <InputGroupAddon align="inline-end">
      <Dropdown>
        <DropdownTrigger asChild>
          <InputGroupButton variant="ghost" class="!pr-1.5 text-xs">
            Search in
            <ChevronDown class="size-3" />
          </InputGroupButton>
        </DropdownTrigger>
        <DropdownContent align="end" class="[--radius:0.95rem]">
          <DropdownItem>Documentation</DropdownItem>
          <DropdownItem>Blog Posts</DropdownItem>
          <DropdownItem>Changelog</DropdownItem>
        </DropdownContent>
      </Dropdown>
    </InputGroupAddon>
  </InputGroup>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Dropdown, DropdownContent, DropdownItem, DropdownTrigger } from "@/components/starwind/dropdown";
import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from "@/components/starwind/input-group";
import { IconChevronDown as ChevronDown } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <div className="grid w-full max-w-sm gap-4">
        <InputGroup>
          <InputGroupInput placeholder="Enter file name" />
          <InputGroupAddon align="inline-end">
            <Dropdown>
              <DropdownTrigger asChild>
                <InputGroupButton aria-label="More options" size="icon-sm">
                  <ChevronDown />
                </InputGroupButton>
              </DropdownTrigger>
              <DropdownContent align="end">
                <DropdownItem>Settings</DropdownItem>
                <DropdownItem>Copy path</DropdownItem>
                <DropdownItem>Open location</DropdownItem>
              </DropdownContent>
            </Dropdown>
          </InputGroupAddon>
        </InputGroup>

<InputGroup className="[--radius:1rem]">
          <InputGroupInput placeholder="Enter search query" />
          <InputGroupAddon align="inline-end">
            <Dropdown>
              <DropdownTrigger asChild>
                <InputGroupButton variant="ghost" className="!pr-1.5 text-xs">
                  Search in
                  <ChevronDown className="size-3" />
                </InputGroupButton>
              </DropdownTrigger>
              <DropdownContent align="end" className="[--radius:0.95rem]">
                <DropdownItem>Documentation</DropdownItem>
                <DropdownItem>Blog Posts</DropdownItem>
                <DropdownItem>Changelog</DropdownItem>
              </DropdownContent>
            </Dropdown>
          </InputGroupAddon>
        </InputGroup>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

#### Spinner

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
} from "@/components/starwind/input-group";
import { Spinner } from "@/components/starwind/spinner";
---

<InputGroup>
    <InputGroupInput placeholder="Saving changes..." />
    <InputGroupAddon align="inline-end">
      <InputGroupText>Saving...</InputGroupText>
      <Spinner />
    </InputGroupAddon>
  </InputGroup>
</div>
```
  </div>
  <div slot="react">
```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
} from "@/components/starwind/input-group";
import { Spinner } from "@/components/starwind/spinner";

export function Example() {
  return (
    <>
      <div className="grid w-full max-w-sm gap-4">
        <InputGroup>
          <InputGroupInput placeholder="Searching..." />
          <InputGroupAddon align="inline-end">
            <Spinner />
          </InputGroupAddon>
        </InputGroup>

<InputGroup>
          <InputGroupInput placeholder="Saving changes..." />
          <InputGroupAddon align="inline-end">
            <InputGroupText>Saving...</InputGroupText>
            <Spinner />
          </InputGroupAddon>
        </InputGroup>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

#### Textarea

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/starwind/input-group";
import ArrowRight from "@tabler/icons/outline/arrow-right.svg";
import Code from "@tabler/icons/outline/code.svg";
import Copy from "@tabler/icons/outline/copy.svg";
---

<InputGroup>
  <InputGroupTextarea
    id="textarea-code"
    placeholder="console.log('Hello, world!');"
    class="min-h-[180px] font-mono text-sm"
  />
  <InputGroupAddon align="block-end" class="border-t">
    <InputGroupText>Line 1, Column 1</InputGroupText>
    <InputGroupButton size="sm" class="ml-auto" variant="default">
      Run
      <ArrowRight />
    </InputGroupButton>
  </InputGroupAddon>
  <InputGroupAddon align="block-start" class="border-b">
    <InputGroupText class="font-mono font-medium">
      <Code />
      script.js
    </InputGroupText>
    <InputGroupButton class="ml-auto" size="icon-sm" aria-label="Copy code">
      <Copy />
    </InputGroupButton>
  </InputGroupAddon>
</InputGroup>
```
  </div>
  <div slot="react">
```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/starwind/input-group";
import { IconArrowRight as ArrowRight } from "@tabler/icons-react";
import { IconCode as Code } from "@tabler/icons-react";
import { IconCopy as Copy } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <InputGroup>
        <InputGroupTextarea
          id="textarea-code"
          placeholder="console.log('Hello, world!');"
          className="min-h-[180px] font-mono text-sm"
        />
        <InputGroupAddon align="block-end" className="border-t">
          <InputGroupText>Line 1, Column 1</InputGroupText>
          <InputGroupButton size="sm" className="ml-auto" variant="default">
            Run
            <ArrowRight />
          </InputGroupButton>
        </InputGroupAddon>
        <InputGroupAddon align="block-start" className="border-b">
          <InputGroupText className="font-mono font-medium">
            <Code />
            script.js
          </InputGroupText>
          <InputGroupButton className="ml-auto" size="icon-sm" aria-label="Copy code">
            <Copy />
          </InputGroupButton>
        </InputGroupAddon>
      </InputGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### InputGroup
- Inherits div attributes.

### InputGroupAddon
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `align` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | No | `"inline-start"` | Styled variant | Aligns the component within its available axis. |
- Inherits div attributes.

### InputGroupButton
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "icon-sm"` | No | `"sm"` | Styled variant | Selects the component's visual size. |
- Inherits Button props. Omits `size`.

### InputGroupInput
- Inherits Input props.

### InputGroupText
- Inherits span attributes.

### InputGroupTextarea
- Inherits Textarea props.

## Changelog

### v1.1.2

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v1.1.1

- Aligned Astro and React attribute forwarding with the current generated adapter output.

### v1.1.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.
- `InputGroupAddon` is now presentational and no longer installs a click-to-focus script. Give the
control its own accessible name, and use `InputGroupButton` when the addon itself performs an
action.

### v1.0.1

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.16.0

---

Source: [https://starwind.dev/docs/components/input-otp/](https://starwind.dev/docs/components/input-otp/) · [Markdown](https://starwind.dev/docs/components/input-otp.md)

# Input OTP

InputOtp,
InputOtpGroup,
InputOtpSeparator,
InputOtpSlot,
REGEXP_ONLY_DIGITS_AND_CHARS,
} from "@/components/starwind/input-otp";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSlot,
} from "@/components/starwind/input-otp";
---

<InputOtp aria-label="Verification code" maxLength={6}>
  <InputOtpGroup>
    <InputOtpSlot index={0} />
    <InputOtpSlot index={1} />
    <InputOtpSlot index={2} />
    <InputOtpSlot index={3} />
    <InputOtpSlot index={4} />
    <InputOtpSlot index={5} />
  </InputOtpGroup>
</InputOtp>
```
  </div>
  <div slot="react">
```tsx
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSlot,
} from "@/components/starwind/input-otp";

export function Example() {
  return (
    <InputOtp aria-label="Verification code" maxLength={6}>
      <InputOtpGroup>
        <InputOtpSlot index={0} />
        <InputOtpSlot index={1} />
        <InputOtpSlot index={2} />
        <InputOtpSlot index={3} />
        <InputOtpSlot index={4} />
        <InputOtpSlot index={5} />
      </InputOtpGroup>
    </InputOtp>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add input-otp
```

## Usage

### General Notes

The Input OTP component provides a user-friendly way to input one-time passwords and verification codes. It supports keyboard navigation, paste handling, and pattern validation.

The essential components are `InputOtp`, `InputOtpGroup`, and `InputOtpSlot`. The `InputOtpSeparator` provides visual separation between groups of slots.

### With Separator

Use `InputOtpSeparator` to visually group slots, commonly used for phone verification codes or formatted inputs.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSeparator,
  InputOtpSlot,
} from "@/components/starwind/input-otp";
---

<InputOtp aria-label="Verification code with separator" maxLength={6}>
  <InputOtpGroup>
    <InputOtpSlot index={0} />
    <InputOtpSlot index={1} />
    <InputOtpSlot index={2} />
  </InputOtpGroup>
  <InputOtpSeparator />
  <InputOtpGroup>
    <InputOtpSlot index={3} />
    <InputOtpSlot index={4} />
    <InputOtpSlot index={5} />
  </InputOtpGroup>
</InputOtp>
```
  </div>
  <div slot="react">
```tsx
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSeparator,
  InputOtpSlot,
} from "@/components/starwind/input-otp";

export function Example() {
  return (
    <>
      <InputOtp aria-label="Verification code with separator" maxLength={6}>
        <InputOtpGroup>
          <InputOtpSlot index={0} />
          <InputOtpSlot index={1} />
          <InputOtpSlot index={2} />
        </InputOtpGroup>
        <InputOtpSeparator />
        <InputOtpGroup>
          <InputOtpSlot index={3} />
          <InputOtpSlot index={4} />
          <InputOtpSlot index={5} />
        </InputOtpGroup>
      </InputOtp>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Name the `InputOtp` root rather than its individual slots; Runtime exposes the shared name on the
hidden input.

### Alphanumeric Pattern

Use the `pattern` prop with `REGEXP_ONLY_DIGITS_AND_CHARS` to allow both letters and numbers.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSlot,
  REGEXP_ONLY_DIGITS_AND_CHARS,
} from "@/components/starwind/input-otp";
---

<InputOtp
  aria-label="Alphanumeric verification code"
  maxLength={6}
  pattern={REGEXP_ONLY_DIGITS_AND_CHARS}
>
  <InputOtpGroup>
    <InputOtpSlot index={0} />
    <InputOtpSlot index={1} />
    <InputOtpSlot index={2} />
    <InputOtpSlot index={3} />
    <InputOtpSlot index={4} />
    <InputOtpSlot index={5} />
  </InputOtpGroup>
</InputOtp>
```
  </div>
  <div slot="react">
```tsx
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSlot,
  REGEXP_ONLY_DIGITS_AND_CHARS,
} from "@/components/starwind/input-otp";

export function Example() {
  return (
    <>
      <InputOtp
        aria-label="Alphanumeric verification code"
        maxLength={6}
        pattern={REGEXP_ONLY_DIGITS_AND_CHARS}
      >
        <InputOtpGroup>
          <InputOtpSlot index={0} />
          <InputOtpSlot index={1} />
          <InputOtpSlot index={2} />
          <InputOtpSlot index={3} />
          <InputOtpSlot index={4} />
          <InputOtpSlot index={5} />
        </InputOtpGroup>
      </InputOtp>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Keep an explicit accessible name when the pattern changes what characters the shared input
accepts.

### Sizes

Set `size="sm"`, `size="md"` (the default), or `size="lg"` once on `InputOtp`. Every slot in the
code field inherits that physical visual scale; `InputOtpSlot` no longer accepts `size`.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSlot,
} from "@/components/starwind/input-otp";
---

<div class="flex flex-col gap-6">
  <div class="space-y-2">
    <p class="text-muted-foreground text-sm">Small</p>
    <InputOtp size="sm" aria-label="Small verification code" maxLength={4}>
      <InputOtpGroup>
        <InputOtpSlot index={0} />
        <InputOtpSlot index={1} />
        <InputOtpSlot index={2} />
        <InputOtpSlot index={3} />
      </InputOtpGroup>
    </InputOtp>
  </div>
  <div class="space-y-2">
    <p class="text-muted-foreground text-sm">Medium (default)</p>
    <InputOtp size="md" aria-label="Medium verification code" maxLength={4}>
      <InputOtpGroup>
        <InputOtpSlot index={0} />
        <InputOtpSlot index={1} />
        <InputOtpSlot index={2} />
        <InputOtpSlot index={3} />
      </InputOtpGroup>
    </InputOtp>
  </div>
  <div class="space-y-2">
    <p class="text-muted-foreground text-sm">Large</p>
    <InputOtp size="lg" aria-label="Large verification code" maxLength={4}>
      <InputOtpGroup>
        <InputOtpSlot index={0} />
        <InputOtpSlot index={1} />
        <InputOtpSlot index={2} />
        <InputOtpSlot index={3} />
      </InputOtpGroup>
    </InputOtp>
  </div>
</div>
```
  </div>
  <div slot="react">
```tsx
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSlot,
} from "@/components/starwind/input-otp";

export function Example() {
  return (
    <>
      <div className="flex flex-col gap-6">
        <div className="space-y-2">
          <p className="text-muted-foreground text-sm">Small</p>
          <InputOtp size="sm" aria-label="Small verification code" maxLength={4}>
            <InputOtpGroup>
              <InputOtpSlot index={0} />
              <InputOtpSlot index={1} />
              <InputOtpSlot index={2} />
              <InputOtpSlot index={3} />
            </InputOtpGroup>
          </InputOtp>
        </div>
        <div className="space-y-2">
          <p className="text-muted-foreground text-sm">Medium (default)</p>
          <InputOtp size="md" aria-label="Medium verification code" maxLength={4}>
            <InputOtpGroup>
              <InputOtpSlot index={0} />
              <InputOtpSlot index={1} />
              <InputOtpSlot index={2} />
              <InputOtpSlot index={3} />
            </InputOtpGroup>
          </InputOtp>
        </div>
        <div className="space-y-2">
          <p className="text-muted-foreground text-sm">Large</p>
          <InputOtp size="lg" aria-label="Large verification code" maxLength={4}>
            <InputOtpGroup>
              <InputOtpSlot index={0} />
              <InputOtpSlot index={1} />
              <InputOtpSlot index={2} />
              <InputOtpSlot index={3} />
            </InputOtpGroup>
          </InputOtp>
        </div>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Size is visual, so each preview uses a distinct accessible name instead of relying on the nearby
size caption.

### Disabled

Use the `disabled` prop to prevent user interaction.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSlot,
} from "@/components/starwind/input-otp";
---

<InputOtp aria-label="Verification code" maxLength={6} disabled>
  <InputOtpGroup>
    <InputOtpSlot index={0} />
    <InputOtpSlot index={1} />
    <InputOtpSlot index={2} />
    <InputOtpSlot index={3} />
    <InputOtpSlot index={4} />
    <InputOtpSlot index={5} />
  </InputOtpGroup>
</InputOtp>
```
  </div>
  <div slot="react">
```tsx
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSlot,
} from "@/components/starwind/input-otp";

export function Example() {
  return (
    <>
      <InputOtp aria-label="Verification code" maxLength={6} disabled>
        <InputOtpGroup>
          <InputOtpSlot index={0} />
          <InputOtpSlot index={1} />
          <InputOtpSlot index={2} />
          <InputOtpSlot index={3} />
          <InputOtpSlot index={4} />
          <InputOtpSlot index={5} />
        </InputOtpGroup>
      </InputOtp>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Disabled controls still need an accessible name so assistive technology can identify them.

### Form Submission

The component integrates with native HTML forms using the `name` prop. The hidden input stores the complete OTP value.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import {
  InputOtp,
  InputOtpGroup,
  InputOtpSlot,
} from "@/components/starwind/input-otp";
import { Label } from "@/components/starwind/label";
---

<form id="otp-demo-form" class="space-y-4">
  <div class="space-y-2">
    <Label for="otp-form">Verification Code</Label>
    <InputOtp id="otp-form" name="otp" maxLength={6} required>
      <InputOtpGroup>
        <InputOtpSlot index={0} />
        <InputOtpSlot index={1} />
        <InputOtpSlot index={2} />
        <InputOtpSlot index={3} />
        <InputOtpSlot index={4} />
        <InputOtpSlot index={5} />
      </InputOtpGroup>
    </InputOtp>
  </div>
  <Button type="submit">Submit Code</Button>
</form>
<div id="form-result" class="bg-muted mt-4 hidden rounded-md p-4 font-mono text-sm"></div>

if (form && resultDiv) {
    form.addEventListener("submit", (e) => {
      e.preventDefault();
      const formData = new FormData(form);
      const otp = formData.get("otp");

resultDiv.textContent = `Submitted OTP: ${otp}`;
      resultDiv.classList.remove("hidden");
    });
  }
</script>
```
  </div>
  <div slot="react">
```tsx
import type { FormEvent } from "react";
import { useState } from "react";
import { Button } from "@/components/starwind/button";
import { InputOtp, InputOtpGroup, InputOtpSlot } from "@/components/starwind/input-otp";
import { Label } from "@/components/starwind/label";

export function Example() {
  const [submittedOtp, setSubmittedOtp] = useState<string | null>(null);

function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setSubmittedOtp(String(new FormData(event.currentTarget).get("otp") ?? ""));
  }

return (
    <>
      <form className="space-y-4" onSubmit={handleSubmit}>
        <div className="space-y-2">
          <Label htmlFor="otp-form">Verification Code</Label>
          <InputOtp id="otp-form" name="otp" maxLength={6} required>
            <InputOtpGroup>
              {Array.from({ length: 6 }, (_, index) => (
                <InputOtpSlot key={index} index={index} />
              ))}
            </InputOtpGroup>
          </InputOtp>
        </div>
        <Button type="submit">Submit Code</Button>
      </form>
      {submittedOtp !== null ? (
        <div className="bg-muted mt-4 rounded-md p-4 font-mono text-sm">
          Submitted OTP: {submittedOtp}
        </div>
      ) : null}
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Value changes

Listen on the Input OTP root for `starwind:value-change`. Its detail includes `value`,
`previousValue`, `reason`, and `inputOtpId`; the event is cancelable before Runtime commits the
change.

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<InputOtp id="verification-code" aria-label="Verification code" maxLength={6}>
  <InputOtpGroup>
    <InputOtpSlot index={0} />
    <InputOtpSlot index={1} />
    <InputOtpSlot index={2} />
    <InputOtpSlot index={3} />
    <InputOtpSlot index={4} />
    <InputOtpSlot index={5} />
  </InputOtpGroup>
</InputOtp>

export function Example() {
  return (
    <InputOtp
      aria-label="Verification code"
      maxLength={6}
      onValueChange={(value, details) => console.log(value, details.reason)}
    >
      <InputOtpGroup>
        {Array.from({ length: 6 }, (_, index) => (
          <InputOtpSlot key={index} index={index} />
        ))}
      </InputOtpGroup>
    </InputOtp>
  );
}
```
</div>
</FrameworkCodeSwitcher>

### Size migration

| Before | After |
| --- | --- |
| `<InputOtp><InputOtpSlot index={0} size="lg" /></InputOtp>` | `<InputOtp size="lg"><InputOtpSlot index={0} /></InputOtp>` |

## API Reference
### InputOtp
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Wrapper prop | Selects the component's visual size. |
- Inherits div attributes. Omits `defaultValue`, `id`, `onChange`, `pattern`, and `value`.

### InputOtpGroup
- Inherits div attributes.

### InputOtpSlot
- Inherits div attributes.

### InputOtpSeparator
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Input OTP Primitive](/docs/primitives/input-otp/)
- Runtime factory: [`createInputOtp`](/docs/runtime/#create-input-otp) from `@starwind-ui/runtime/input-otp`

## Changelog

### v3.0.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v3.0.0

- Moved slot sizing from `InputOtpSlot` to the `InputOtp` root, with `md` as the default.
- Migration: `<InputOtpSlot index={0} size="sm" />` becomes
`<InputOtp size="sm"><InputOtpSlot index={0} /></InputOtp>`.

### v2.0.0

- Rebuilt Input OTP on Starwind Runtime for value state, form participation, paste handling, and value-change events.
- See the [Input OTP Primitive](/docs/primitives/input-otp/) for the underlying unstyled anatomy and behavior API.
- Input OTP now delegates keyboard navigation, paste distribution, pattern filtering, hidden form
input synchronization, and reset behavior to the Runtime. Give the root an accessible name
because its visible slots share one hidden input.

### v1.0.3

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.1

- Auto focus hidden input on click to automatically open keyboards on mobile devices
- Update component to always focus the next empty index on click

### v1.0.0

- Initial release with starwind v1.15.0

---

Source: [https://starwind.dev/docs/components/item/](https://starwind.dev/docs/components/item/) · [Markdown](https://starwind.dev/docs/components/item.md)

# Item

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia } from "@/components/starwind/item";
import { Button } from "@/components/starwind/button";
import CircleCheck from "@tabler/icons/outline/circle-check.svg";
import ChevronRight from "@tabler/icons/outline/chevron-right.svg";
---

<Item variant="outline">
  <ItemContent>
    <ItemTitle>Basic Item</ItemTitle>
    <ItemDescription>A simple item with title and description.</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button variant="outline" size="sm">Action</Button>
  </ItemActions>
</Item>

<Item variant="outline" size="sm" as="a" href="#">
  <ItemMedia>
    <CircleCheck class="size-5" />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Your profile has been verified.</ItemTitle>
  </ItemContent>
  <ItemActions>
    <ChevronRight class="size-4" />
  </ItemActions>
</Item>
```
  </div>
  <div slot="react">
```tsx
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia } from "@/components/starwind/item";
import { Button } from "@/components/starwind/button";
import { IconChevronRight, IconCircleCheck } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <Item variant="outline">
        <ItemContent>
          <ItemTitle>Basic Item</ItemTitle>
          <ItemDescription>A simple item with title and description.</ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button variant="outline" size="sm">Action</Button>
        </ItemActions>
      </Item>

<Item variant="outline" size="sm" as="a" href="#">
        <ItemMedia>
          <IconCircleCheck className="size-5" />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Your profile has been verified.</ItemTitle>
        </ItemContent>
        <ItemActions>
          <IconChevronRight className="size-4" />
        </ItemActions>
      </Item>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add item
```

## Usage

### Icon

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia } from "@/components/starwind/item";
import { Button } from "@/components/starwind/button";
import AlertHexagon from "@tabler/icons/outline/alert-hexagon.svg";
---

<Item variant="outline">
  <ItemMedia variant="icon">
    <AlertHexagon />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Security Alert</ItemTitle>
    <ItemDescription>New login detected from unknown device.</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button size="sm" variant="outline">Review</Button>
  </ItemActions>
</Item>
```
  </div>
  <div slot="react">
```tsx
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia } from "@/components/starwind/item";
import { Button } from "@/components/starwind/button";
import { IconAlertHexagon as AlertHexagon } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <Item variant="outline">
        <ItemMedia variant="icon">
          <AlertHexagon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Security Alert</ItemTitle>
          <ItemDescription>New login detected from unknown device.</ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button size="sm" variant="outline">Review</Button>
        </ItemActions>
      </Item>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Avatar

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia } from "@/components/starwind/item";
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
import { Button } from "@/components/starwind/button";
import Plus from "@tabler/icons/outline/plus.svg";
---

<Item variant="outline">
  <ItemMedia>
    <Avatar >
      <AvatarImage src="https://github.com/Boston343.png" alt="@boston343builds" />
      <AvatarFallback>BB</AvatarFallback>
    </Avatar>
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Branden</ItemTitle>
    <ItemDescription>Last seen 5 months ago</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button size="icon-sm" variant="outline" class="rounded-full" aria-label="Invite">
      <Plus />
    </Button>
  </ItemActions>
</Item>
<Item variant="outline">
  <ItemMedia>
    <div class="flex -space-x-3">
      <Avatar class="hidden sm:flex ">
        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
      <Avatar class="hidden sm:flex z-1">
        <AvatarImage src="https://github.com/maxleiter.png" alt="@maxleiter" />
        <AvatarFallback>LR</AvatarFallback>
      </Avatar>
      <Avatar class="z-2">
        <AvatarImage src="https://github.com/Boston343.png" alt="@boston343builds" />
        <AvatarFallback>BB</AvatarFallback>
      </Avatar>
    </div>
  </ItemMedia>
  <ItemContent>
    <ItemTitle>No Team Members</ItemTitle>
    <ItemDescription>Invite your team to collaborate on this project.</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button size="sm" variant="outline">Invite</Button>
  </ItemActions>
</Item>
```
  </div>
  <div slot="react">
```tsx
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia } from "@/components/starwind/item";
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
import { Button } from "@/components/starwind/button";
import { IconPlus as Plus } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <Item variant="outline">
        <ItemMedia>
          <Avatar >
            <AvatarImage src="https://github.com/Boston343.png" alt="@boston343builds" />
            <AvatarFallback>BB</AvatarFallback>
          </Avatar>
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Branden</ItemTitle>
          <ItemDescription>Last seen 5 months ago</ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button size="icon-sm" variant="outline" className="rounded-full" aria-label="Invite">
            <Plus />
          </Button>
        </ItemActions>
      </Item>
      <Item variant="outline">
        <ItemMedia>
          <div className="flex -space-x-3">
            <Avatar className="hidden sm:flex ">
              <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
              <AvatarFallback>CN</AvatarFallback>
            </Avatar>
            <Avatar className="hidden sm:flex z-1">
              <AvatarImage src="https://github.com/maxleiter.png" alt="@maxleiter" />
              <AvatarFallback>LR</AvatarFallback>
            </Avatar>
            <Avatar className="z-2">
              <AvatarImage src="https://github.com/Boston343.png" alt="@boston343builds" />
              <AvatarFallback>BB</AvatarFallback>
            </Avatar>
          </div>
        </ItemMedia>
        <ItemContent>
          <ItemTitle>No Team Members</ItemTitle>
          <ItemDescription>Invite your team to collaborate on this project.</ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button size="sm" variant="outline">Invite</Button>
        </ItemActions>
      </Item>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Image

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Item, ItemContent, ItemTitle, ItemDescription, ItemMedia, ItemGroup } from "@/components/starwind/item";
---

<ItemGroup class="gap-4">
  <Item variant="outline" as="a" href="#">
    <ItemMedia variant="image">
      <img
        src="https://avatar.vercel.sh/Midnight-City-Lights"
        alt="Midnight City Lights"
        class="object-cover grayscale"
      />
    </ItemMedia>
    <ItemContent>
      <ItemTitle class="line-clamp-1">
        Midnight City Lights - <span class="text-muted-foreground">Electric Nights</span>
      </ItemTitle>
      <ItemDescription>Neon Dreams</ItemDescription>
    </ItemContent>
    <ItemContent class="flex-none text-center">
      <ItemDescription>3:45</ItemDescription>
    </ItemContent>
  </Item>
  
</ItemGroup>
```
  </div>
  <div slot="react">
```tsx
import { Item, ItemContent, ItemTitle, ItemDescription, ItemMedia, ItemGroup } from "@/components/starwind/item";

export function Example() {
  return (
    <>
      <ItemGroup className="gap-4">
        <Item variant="outline" as="a" href="#">
          <ItemMedia variant="image">
            <img
              src="https://avatar.vercel.sh/Midnight-City-Lights"
              alt="Midnight City Lights"
              className="object-cover grayscale"
            />
          </ItemMedia>
          <ItemContent>
            <ItemTitle className="line-clamp-1">
              Midnight City Lights - <span className="text-muted-foreground">Electric Nights</span>
            </ItemTitle>
            <ItemDescription>Neon Dreams</ItemDescription>
          </ItemContent>
          <ItemContent className="flex-none text-center">
            <ItemDescription>3:45</ItemDescription>
          </ItemContent>
        </Item>
        {/* More items... */}
      </ItemGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### variant

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions } from "@/components/starwind/item";
import { Button } from "@/components/starwind/button";
---

<Item>
  <ItemContent>
    <ItemTitle>Default Variant</ItemTitle>
    <ItemDescription>
      Standard styling with subtle background and borders.
    </ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button variant="outline" size="sm">Open</Button>
  </ItemActions>
</Item>

<Item variant="outline">
  <ItemContent>
    <ItemTitle>Outline Variant</ItemTitle>
    <ItemDescription>
      Outlined style with clear borders and transparent background.
    </ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button variant="outline" size="sm">Open</Button>
  </ItemActions>
</Item>

<Item variant="muted">
  <ItemContent>
    <ItemTitle>Muted Variant</ItemTitle>
    <ItemDescription>
      Subdued appearance with muted colors for secondary content.
    </ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button variant="outline" size="sm">Open</Button>
  </ItemActions>
</Item>
```
  </div>
  <div slot="react">
```tsx
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions } from "@/components/starwind/item";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Item>
        <ItemContent>
          <ItemTitle>Default Variant</ItemTitle>
          <ItemDescription>
            Standard styling with subtle background and borders.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button variant="outline" size="sm">Open</Button>
        </ItemActions>
      </Item>

<Item variant="outline">
        <ItemContent>
          <ItemTitle>Outline Variant</ItemTitle>
          <ItemDescription>
            Outlined style with clear borders and transparent background.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button variant="outline" size="sm">Open</Button>
        </ItemActions>
      </Item>

<Item variant="muted">
        <ItemContent>
          <ItemTitle>Muted Variant</ItemTitle>
          <ItemDescription>
            Subdued appearance with muted colors for secondary content.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button variant="outline" size="sm">Open</Button>
        </ItemActions>
      </Item>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Size

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Item, ItemContent, ItemTitle, ItemDescription } from "@/components/starwind/item";
---

<Item variant="outline" size="md">
  <ItemContent>
    <ItemTitle>Medium Size</ItemTitle>
    <ItemDescription>The default padding and spacing for most use cases.</ItemDescription>
  </ItemContent>
</Item>

<Item variant="outline" size="sm">
  <ItemContent>
    <ItemTitle>Small Size</ItemTitle>
    <ItemDescription>Compact padding for dense layouts.</ItemDescription>
  </ItemContent>
</Item>
```
  </div>
  <div slot="react">
```tsx
import { Item, ItemContent, ItemTitle, ItemDescription } from "@/components/starwind/item";

export function Example() {
  return (
    <>
      <Item variant="outline" size="md">
        <ItemContent>
          <ItemTitle>Medium Size</ItemTitle>
          <ItemDescription>The default padding and spacing for most use cases.</ItemDescription>
        </ItemContent>
      </Item>

<Item variant="outline" size="sm">
        <ItemContent>
          <ItemTitle>Small Size</ItemTitle>
          <ItemDescription>Compact padding for dense layouts.</ItemDescription>
        </ItemContent>
      </Item>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Group

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia, ItemGroup, ItemSeparator } from "@/components/starwind/item";
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
import { Button } from "@/components/starwind/button";
import Plus from "@tabler/icons/outline/plus.svg";
---

<ItemGroup>
  <Item>
    <ItemMedia>
      <Avatar>
        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
    </ItemMedia>
    <ItemContent class="gap-1">
      <ItemTitle>shadcn</ItemTitle>
      <ItemDescription>shadcn@vercel.com</ItemDescription>
    </ItemContent>
    <ItemActions>
      <Button variant="ghost" size="icon" class="rounded-full">
        <Plus />
      </Button>
    </ItemActions>
  </Item>
  <ItemSeparator />
  
</ItemGroup>
```
  </div>
  <div slot="react">
```tsx
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia, ItemGroup, ItemSeparator } from "@/components/starwind/item";
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
import { Button } from "@/components/starwind/button";
import { IconPlus as Plus } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <ItemGroup>
        <Item>
          <ItemMedia>
            <Avatar>
              <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
              <AvatarFallback>CN</AvatarFallback>
            </Avatar>
          </ItemMedia>
          <ItemContent className="gap-1">
            <ItemTitle>shadcn</ItemTitle>
            <ItemDescription>shadcn@vercel.com</ItemDescription>
          </ItemContent>
          <ItemActions>
            <Button variant="ghost" size="icon" className="rounded-full">
              <Plus />
            </Button>
          </ItemActions>
        </Item>
        <ItemSeparator />
        {/* More items... */}
      </ItemGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Header

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Item, ItemContent, ItemTitle, ItemDescription, ItemHeader, ItemGroup } from "@/components/starwind/item";
---

<ItemGroup class="grid grid-cols-3 gap-4">
  <Item variant="outline">
    <ItemHeader>
      <img
        src="https://images.unsplash.com/photo-1650804068570-7fb2e3dbf888?q=80&w=640&auto=format&fit=crop"
        alt="v0-1.5-sm"
        class="aspect-square w-full rounded-sm object-cover"
      />
    </ItemHeader>
    <ItemContent>
      <ItemTitle>v0-1.5-sm</ItemTitle>
      <ItemDescription>Everyday tasks and UI generation.</ItemDescription>
    </ItemContent>
  </Item>
  
</ItemGroup>
```
  </div>
  <div slot="react">
```tsx
import { Item, ItemContent, ItemTitle, ItemDescription, ItemHeader, ItemGroup } from "@/components/starwind/item";

export function Example() {
  return (
    <>
      <ItemGroup className="grid grid-cols-3 gap-4">
        <Item variant="outline">
          <ItemHeader>
            <img
              src="https://images.unsplash.com/photo-1650804068570-7fb2e3dbf888?q=80&w=640&auto=format&fit=crop"
              alt="v0-1.5-sm"
              className="aspect-square w-full rounded-sm object-cover"
            />
          </ItemHeader>
          <ItemContent>
            <ItemTitle>v0-1.5-sm</ItemTitle>
            <ItemDescription>Everyday tasks and UI generation.</ItemDescription>
          </ItemContent>
        </Item>
        {/* More items... */}
      </ItemGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Link

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions } from "@/components/starwind/item";
import ChevronRight from "@tabler/icons/outline/chevron-right.svg";
import ExternalLink from "@tabler/icons/outline/external-link.svg";
---

<Item as="a" href="#">
  <ItemContent>
    <ItemTitle>Visit our documentation</ItemTitle>
    <ItemDescription>Learn how to get started with our components.</ItemDescription>
  </ItemContent>
  <ItemActions>
    <ChevronRight class="size-4" />
  </ItemActions>
</Item>

<Item variant="outline" as="a" href="#" target="_blank" rel="noopener noreferrer">
  <ItemContent>
    <ItemTitle>External resource</ItemTitle>
    <ItemDescription>Opens in a new tab with security attributes.</ItemDescription>
  </ItemContent>
  <ItemActions>
    <ExternalLink class="size-4" />
  </ItemActions>
</Item>
```
  </div>
  <div slot="react">
```tsx
import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions } from "@/components/starwind/item";
import { IconChevronRight as ChevronRight } from "@tabler/icons-react";
import { IconExternalLink as ExternalLink } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <Item as="a" href="#">
        <ItemContent>
          <ItemTitle>Visit our documentation</ItemTitle>
          <ItemDescription>Learn how to get started with our components.</ItemDescription>
        </ItemContent>
        <ItemActions>
          <ChevronRight className="size-4" />
        </ItemActions>
      </Item>

### Dropdown

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Item, ItemContent, ItemTitle, ItemDescription, ItemMedia } from "@/components/starwind/item";
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
import { Button } from "@/components/starwind/button";
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from "@/components/starwind/dropdown";
import ChevronDown from "@tabler/icons/outline/chevron-down.svg";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button variant="outline" size="sm" class="w-fit">
      Select
      <ChevronDown />
    </Button>
  </DropdownTrigger>
  <DropdownContent class="min-w-60" align="end">
    <DropdownItem class="p-0">
      <Item size="sm" class="w-full p-2">
        <ItemMedia>
          <Avatar class="size-8">
            <AvatarImage src="https://github.com/Boston343.png" alt="@boston343builds" />
            <AvatarFallback>BB</AvatarFallback>
          </Avatar>
        </ItemMedia>
        <ItemContent class="gap-0.5">
          <ItemTitle>Branden</ItemTitle>
          <ItemDescription>Creator of Starwind UI</ItemDescription>
        </ItemContent>
      </Item>
    </DropdownItem>
    
  </DropdownContent>
</Dropdown>
```
  </div>
  <div slot="react">
```tsx
import { Item, ItemContent, ItemTitle, ItemDescription, ItemMedia } from "@/components/starwind/item";
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
import { Button } from "@/components/starwind/button";
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from "@/components/starwind/dropdown";
import { IconChevronDown as ChevronDown } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <Dropdown>
        <DropdownTrigger asChild>
          <Button variant="outline" size="sm" className="w-fit">
            Select
            <ChevronDown />
          </Button>
        </DropdownTrigger>
        <DropdownContent className="min-w-60" align="end">
          <DropdownItem className="p-0">
            <Item size="sm" className="w-full p-2">
              <ItemMedia>
                <Avatar className="size-8">
                  <AvatarImage src="https://github.com/Boston343.png" alt="@boston343builds" />
                  <AvatarFallback>BB</AvatarFallback>
                </Avatar>
              </ItemMedia>
              <ItemContent className="gap-0.5">
                <ItemTitle>Branden</ItemTitle>
                <ItemDescription>Creator of Starwind UI</ItemDescription>
              </ItemContent>
            </Item>
          </DropdownItem>
          {/* More items... */}
        </DropdownContent>
      </Dropdown>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Item
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `as` | `keyof HTMLElementTagNameMap` | No | `"div"` | Wrapper prop | Selects the rendered element or component. |
| `size` | `"sm" \| "md"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `variant` | `"default" \| "outline" \| "muted"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits a attributes. Omits `type`.
- Inherits div attributes.

### ItemActions
- Inherits div attributes.

### ItemContent
- Inherits div attributes.

### ItemDescription
- Inherits p attributes.

### ItemFooter
- Inherits div attributes.

### ItemGroup
- Inherits div attributes.

### ItemHeader
- Inherits div attributes.

### ItemMedia
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `"default" \| "icon" \| "image"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits div attributes.

### ItemSeparator
- Inherits Separator props.

### ItemTitle
- Inherits div attributes.

## Changelog

### v1.2.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v1.2.0

- Renamed the standard Item size from `default` to `md`. Omitting `size` keeps the same medium spacing.

### v1.1.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v1.0.3

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.10.0

---

Source: [https://starwind.dev/docs/components/kbd/](https://starwind.dev/docs/components/kbd/) · [Markdown](https://starwind.dev/docs/components/kbd.md)

# Kbd

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Kbd } from "@/components/starwind/kbd";
---

<div class="flex items-center gap-2">
  <span class="text-sm text-muted-foreground">Press</span>
  <Kbd>Ctrl</Kbd>
  <span class="text-sm text-muted-foreground">to continue</span>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Kbd } from "@/components/starwind/kbd";

export function Example() {
  return (
    <div className="flex items-center gap-2">
      <span className="text-sm text-muted-foreground">Press</span>
      <Kbd>Ctrl</Kbd>
      <span className="text-sm text-muted-foreground">to continue</span>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add kbd
```

## Usage

### Basic

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Kbd } from "@/components/starwind/kbd";
---

<Kbd>Ctrl</Kbd>
<Kbd>Shift</Kbd>
<Kbd>Alt</Kbd>
<Kbd>⌘</Kbd>
<Kbd>⏎</Kbd>
<Kbd>Esc</Kbd>
```
  </div>
  <div slot="react">
```tsx
import { Kbd } from "@/components/starwind/kbd";

export function Example() {
  return (
    <>
      <Kbd>Ctrl</Kbd>
      <Kbd>Shift</Kbd>
      <Kbd>Alt</Kbd>
      <Kbd>⌘</Kbd>
      <Kbd>⏎</Kbd>
      <Kbd>Esc</Kbd>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Group

Use the `KbdGroup` component to group keyboard keys together.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Kbd, KbdGroup } from "@/components/starwind/kbd";
---

<p class="text-sm text-muted-foreground">
  Use{" "}
  <KbdGroup>
    <Kbd>Ctrl</Kbd>
    <span>+</span>
    <Kbd>K</Kbd>
  </KbdGroup>
  {" "}to open the command palette
</p>

<p class="text-sm text-muted-foreground">
  Press{" "}
  <KbdGroup>
    <Kbd>⌘</Kbd>
    <span>+</span>
    <Kbd>Shift</Kbd>
    <span>+</span>
    <Kbd>P</Kbd>
  </KbdGroup>
  {" "}to open command palette
</p>
```
  </div>
  <div slot="react">
```tsx
import { Kbd, KbdGroup } from "@/components/starwind/kbd";

export function Example() {
  return (
    <>
      <p className="text-sm text-muted-foreground">
        Use{" "}
        <KbdGroup>
          <Kbd>Ctrl</Kbd>
          <span>+</span>
          <Kbd>K</Kbd>
        </KbdGroup>
        {" "}to open the command palette
      </p>

<p className="text-sm text-muted-foreground">
        Press{" "}
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <span>+</span>
          <Kbd>Shift</Kbd>
          <span>+</span>
          <Kbd>P</Kbd>
        </KbdGroup>
        {" "}to open command palette
      </p>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### With Button

Use the `Kbd` component inside a `Button` component to display a keyboard key inside a button.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import { Kbd, KbdGroup } from "@/components/starwind/kbd";
---

<Button variant="outline" size="sm" class="pr-2">
  Accept
  <Kbd>⏎</Kbd>
</Button>

<Button variant="outline" size="sm" class="pr-2">
  Cancel
  <Kbd>Esc</Kbd>
</Button>

<Button variant="outline" size="sm" class="pr-2">
  Save
  <KbdGroup>
    <Kbd>Ctrl</Kbd>
    <span>+</span>
    <Kbd>S</Kbd>
  </KbdGroup>
</Button>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import { Kbd, KbdGroup } from "@/components/starwind/kbd";

export function Example() {
  return (
    <>
      <Button variant="outline" size="sm" className="pr-2">
        Accept
        <Kbd>⏎</Kbd>
      </Button>

<Button variant="outline" size="sm" className="pr-2">
        Cancel
        <Kbd>Esc</Kbd>
      </Button>

### Common Shortcuts

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Kbd, KbdGroup } from "@/components/starwind/kbd";
---

<div class="flex flex-col gap-3 min-w-sm">
  <div class="flex items-center gap-3 justify-between">
    <span class="text-sm">Copy</span>
    <KbdGroup>
      <Kbd>Ctrl</Kbd>
      <span>+</span>
      <Kbd>C</Kbd>
    </KbdGroup>
  </div>
  <div class="flex items-center gap-3 justify-between">
    <span class="text-sm">Paste</span>
    <KbdGroup>
      <Kbd>Ctrl</Kbd>
      <span>+</span>
      <Kbd>V</Kbd>
    </KbdGroup>
  </div>
  <div class="flex items-center gap-3 justify-between">
    <span class="text-sm">Cut</span>
    <KbdGroup>
      <Kbd>Ctrl</Kbd>
      <span>+</span>
      <Kbd>X</Kbd>
    </KbdGroup>
  </div>
  <div class="flex items-center gap-3 justify-between">
    <span class="text-sm">Undo</span>
    <KbdGroup>
      <Kbd>Ctrl</Kbd>
      <span>+</span>
      <Kbd>Z</Kbd>
    </KbdGroup>
  </div>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Kbd, KbdGroup } from "@/components/starwind/kbd";

export function Example() {
  return (
    <>
      <div className="flex flex-col gap-3 min-w-sm">
        <div className="flex items-center gap-3 justify-between">
          <span className="text-sm">Copy</span>
          <KbdGroup>
            <Kbd>Ctrl</Kbd>
            <span>+</span>
            <Kbd>C</Kbd>
          </KbdGroup>
        </div>
        <div className="flex items-center gap-3 justify-between">
          <span className="text-sm">Paste</span>
          <KbdGroup>
            <Kbd>Ctrl</Kbd>
            <span>+</span>
            <Kbd>V</Kbd>
          </KbdGroup>
        </div>
        <div className="flex items-center gap-3 justify-between">
          <span className="text-sm">Cut</span>
          <KbdGroup>
            <Kbd>Ctrl</Kbd>
            <span>+</span>
            <Kbd>X</Kbd>
          </KbdGroup>
        </div>
        <div className="flex items-center gap-3 justify-between">
          <span className="text-sm">Undo</span>
          <KbdGroup>
            <Kbd>Ctrl</Kbd>
            <span>+</span>
            <Kbd>Z</Kbd>
          </KbdGroup>
        </div>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Arrow Keys

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Kbd } from "@/components/starwind/kbd";
---

<div class="flex flex-col items-center gap-2">
  <Kbd>↑</Kbd>
  <div class="flex gap-2">
    <Kbd>←</Kbd>
    <Kbd>↓</Kbd>
    <Kbd>→</Kbd>
  </div>
</div>
<p class="text-sm text-muted-foreground">Use arrow keys to navigate</p>
```
  </div>
  <div slot="react">
```tsx
import { Kbd } from "@/components/starwind/kbd";

export function Example() {
  return (
    <>
      <div className="flex flex-col items-center gap-2">
        <Kbd>↑</Kbd>
        <div className="flex gap-2">
          <Kbd>←</Kbd>
          <Kbd>↓</Kbd>
          <Kbd>→</Kbd>
        </div>
      </div>
      <p className="text-sm text-muted-foreground">Use arrow keys to navigate</p>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Kbd
- Inherits kbd attributes.

### KbdGroup
- Inherits kbd attributes.

## Changelog

### v1.1.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v1.1.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v1.0.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.11.0

---

Source: [https://starwind.dev/docs/components/label/](https://starwind.dev/docs/components/label/) · [Markdown](https://starwind.dev/docs/components/label.md)

# Label

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Label } from "@/components/starwind/label";
import { Input } from "@/components/starwind/input";
---

<div class="space-y-2">
  <Label for="demo-input">Email</Label>
  <Input id="demo-input" type="email" placeholder="Enter your email" />
</div>
```
  </div>
  <div slot="react">
```tsx
import { Label } from "@/components/starwind/label";
import { Input } from "@/components/starwind/input";

export function Example() {
  return (
    <div className="space-y-2">
      <Label htmlFor="demo-input">Email</Label>
      <Input id="demo-input" type="email" placeholder="Enter your email" />
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add label
```

## Usage

### size

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Label } from "@/components/starwind/label";
import { Input } from "@/components/starwind/input";
---

<div class="space-y-2">
  <Label size="sm" for="small-input">Small Label</Label>
  <Input id="small-input" size="sm" placeholder="Small input" />
</div>

<div class="space-y-2">
  <Label size="md" for="medium-input">Medium Label</Label>
  <Input id="medium-input" size="md" placeholder="Medium input" />
</div>

<div class="space-y-2">
  <Label size="lg" for="large-input">Large Label</Label>
  <Input id="large-input" size="lg" placeholder="Large input" />
</div>
```
  </div>
  <div slot="react">
```tsx
import { Label } from "@/components/starwind/label";
import { Input } from "@/components/starwind/input";

export function Example() {
  return (
    <>
      <div className="space-y-2">
        <Label size="sm" htmlFor="small-input">Small Label</Label>
        <Input id="small-input" size="sm" placeholder="Small input" />
      </div>

<div className="space-y-2">
        <Label size="md" htmlFor="medium-input">Medium Label</Label>
        <Input id="medium-input" size="md" placeholder="Medium input" />
      </div>

<div className="space-y-2">
        <Label size="lg" htmlFor="large-input">Large Label</Label>
        <Input id="large-input" size="lg" placeholder="Large input" />
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### disabled state

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Label } from "@/components/starwind/label";
import { Input } from "@/components/starwind/input";
---

<div class="space-y-2">
  <Label for="disabled-input">Disabled Input Label</Label>
  <Input id="disabled-input" disabled placeholder="This input is disabled" />
</div>
```
  </div>
  <div slot="react">
```tsx
import { Label } from "@/components/starwind/label";
import { Input } from "@/components/starwind/input";

export function Example() {
  return (
    <>
      <div className="space-y-2">
        <Label htmlFor="disabled-input">Disabled Input Label</Label>
        <Input id="disabled-input" disabled placeholder="This input is disabled" />
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Label
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits label attributes.

## Changelog

### v1.3.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v1.2.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.2.0

- Add `data-slot` attribute to enable global styling updates

### v1.1.0

---

Source: [https://starwind.dev/docs/components/native-select/](https://starwind.dev/docs/components/native-select/) · [Markdown](https://starwind.dev/docs/components/native-select.md)

# Native Select

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<NativeSelect class="w-[240px]">
  <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
  <NativeSelectOption value="apple">Apple</NativeSelectOption>
  <NativeSelectOption value="banana">Banana</NativeSelectOption>
  <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
  <NativeSelectOption value="pineapple">Pineapple</NativeSelectOption>
</NativeSelect>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <NativeSelect className="w-[240px]">
        <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
        <NativeSelectOption value="apple">Apple</NativeSelectOption>
        <NativeSelectOption value="banana">Banana</NativeSelectOption>
        <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
        <NativeSelectOption value="pineapple">Pineapple</NativeSelectOption>
      </NativeSelect>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** For a styled select component, see the [Select](/docs/components/select/) component.

## Installation

```bash
npx starwind@latest add native-select
```

## Usage

### Groups

Use `NativeSelectOptGroup` to organize options into categories.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from "@/components/starwind/native-select";
---

<NativeSelect class="w-[260px]">
  <NativeSelectOption value="" disabled>Select an option</NativeSelectOption>
  <NativeSelectOptGroup label="Fruits">
    <NativeSelectOption value="apple">Apple</NativeSelectOption>
    <NativeSelectOption value="banana">Banana</NativeSelectOption>
  </NativeSelectOptGroup>
  <NativeSelectOptGroup label="Vegetables">
    <NativeSelectOption value="carrot">Carrot</NativeSelectOption>
    <NativeSelectOption value="spinach">Spinach</NativeSelectOption>
  </NativeSelectOptGroup>
</NativeSelect>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <NativeSelect className="w-[260px]">
        <NativeSelectOption value="" disabled>Select an option</NativeSelectOption>
        <NativeSelectOptGroup label="Fruits">
          <NativeSelectOption value="apple">Apple</NativeSelectOption>
          <NativeSelectOption value="banana">Banana</NativeSelectOption>
        </NativeSelectOptGroup>
        <NativeSelectOptGroup label="Vegetables">
          <NativeSelectOption value="carrot">Carrot</NativeSelectOption>
          <NativeSelectOption value="spinach">Spinach</NativeSelectOption>
        </NativeSelectOptGroup>
      </NativeSelect>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Disabled

Add the `disabled` prop to disable the entire select, or disable specific options.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<NativeSelect class="w-[220px]" disabled>
  <NativeSelectOption value="" disabled>Select framework</NativeSelectOption>
  <NativeSelectOption value="astro">Astro</NativeSelectOption>
  <NativeSelectOption value="next">Next.js</NativeSelectOption>
</NativeSelect>

<NativeSelect class="w-[220px]">
  <NativeSelectOption value="astro" selected>Astro</NativeSelectOption>
  <NativeSelectOption value="next" disabled>Next.js (Disabled)</NativeSelectOption>
  <NativeSelectOption value="svelte">SvelteKit</NativeSelectOption>
</NativeSelect>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <NativeSelect className="w-[220px]" disabled>
        <NativeSelectOption value="" disabled>Select framework</NativeSelectOption>
        <NativeSelectOption value="astro">Astro</NativeSelectOption>
        <NativeSelectOption value="next">Next.js</NativeSelectOption>
      </NativeSelect>

<NativeSelect className="w-[220px]" defaultValue="astro">
        <NativeSelectOption value="astro">Astro</NativeSelectOption>
        <NativeSelectOption value="next" disabled>Next.js (Disabled)</NativeSelectOption>
        <NativeSelectOption value="svelte">SvelteKit</NativeSelectOption>
      </NativeSelect>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Invalid

Use `aria-invalid` for assistive technology and `data-error-visible` to opt into the visible error
state after validation has run.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Label } from "@/components/starwind/label";
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<div class="grid w-full max-w-sm gap-2">
  <Label for="native-select-invalid">Framework</Label>
  <NativeSelect
    id="native-select-invalid"
    class="w-full"
    aria-invalid
    data-error-visible
  >
    <NativeSelectOption value="" disabled>Select a framework</NativeSelectOption>
    <NativeSelectOption value="astro">Astro</NativeSelectOption>
    <NativeSelectOption value="next">Next.js</NativeSelectOption>
    <NativeSelectOption value="svelte">SvelteKit</NativeSelectOption>
  </NativeSelect>
  <p class="text-error text-sm">Please select a framework.</p>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Label } from "@/components/starwind/label";
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <div className="grid w-full max-w-sm gap-2">
        <Label htmlFor="native-select-invalid">Framework</Label>
        <NativeSelect
          id="native-select-invalid"
          className="w-full"
          aria-invalid
          data-error-visible
        >
          <NativeSelectOption value="" disabled>Select a framework</NativeSelectOption>
          <NativeSelectOption value="astro">Astro</NativeSelectOption>
          <NativeSelectOption value="next">Next.js</NativeSelectOption>
          <NativeSelectOption value="svelte">SvelteKit</NativeSelectOption>
        </NativeSelect>
        <p className="text-error text-sm">Please select a framework.</p>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Size

Use the `size` prop to render compact or larger controls.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<NativeSelect size="sm" class="w-[180px]">
  <NativeSelectOption value="" disabled>Small</NativeSelectOption>
  <NativeSelectOption value="one">Option 1</NativeSelectOption>
  <NativeSelectOption value="two">Option 2</NativeSelectOption>
</NativeSelect>

<NativeSelect size="md" class="w-[180px]">
  <NativeSelectOption value="" disabled>Medium</NativeSelectOption>
  <NativeSelectOption value="one">Option 1</NativeSelectOption>
  <NativeSelectOption value="two">Option 2</NativeSelectOption>
</NativeSelect>

<NativeSelect size="lg" class="w-[180px]">
  <NativeSelectOption value="" disabled>Large</NativeSelectOption>
  <NativeSelectOption value="one">Option 1</NativeSelectOption>
  <NativeSelectOption value="two">Option 2</NativeSelectOption>
</NativeSelect>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <NativeSelect size="sm" className="w-[180px]">
        <NativeSelectOption value="" disabled>Small</NativeSelectOption>
        <NativeSelectOption value="one">Option 1</NativeSelectOption>
        <NativeSelectOption value="two">Option 2</NativeSelectOption>
      </NativeSelect>

<NativeSelect size="md" className="w-[180px]">
        <NativeSelectOption value="" disabled>Medium</NativeSelectOption>
        <NativeSelectOption value="one">Option 1</NativeSelectOption>
        <NativeSelectOption value="two">Option 2</NativeSelectOption>
      </NativeSelect>

<NativeSelect size="lg" className="w-[180px]">
        <NativeSelectOption value="" disabled>Large</NativeSelectOption>
        <NativeSelectOption value="one">Option 1</NativeSelectOption>
        <NativeSelectOption value="two">Option 2</NativeSelectOption>
      </NativeSelect>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Native Select vs Select

Use [Native Select](/docs/components/native-select/) for simple forms when you want browser-native behavior and mobile pickers. Use [Select](/docs/components/select/) when you need custom popover behavior, search, and advanced interaction patterns.

> **Tip:** Prefer `NativeSelect` for straightforward form controls and mobile-first flows where native platform
pickers are beneficial. Choose [Select](/docs/components/select/) when you need richer UI features
like searchable options, custom popover positioning, and advanced interactions.

### RTL

Set `dir="rtl"` to support right-to-left languages.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<div dir="rtl">
  <NativeSelect class="w-[240px]">
    <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
    <NativeSelectOption value="apple">Apple</NativeSelectOption>
    <NativeSelectOption value="banana">Banana</NativeSelectOption>
    <NativeSelectOption value="grape">Grape</NativeSelectOption>
  </NativeSelect>
</div>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <div dir="rtl">
        <NativeSelect className="w-[240px]">
          <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
          <NativeSelectOption value="apple">Apple</NativeSelectOption>
          <NativeSelectOption value="banana">Banana</NativeSelectOption>
          <NativeSelectOption value="grape">Grape</NativeSelectOption>
        </NativeSelect>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### NativeSelect
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits select attributes. Omits `size`.

### NativeSelectOption
- Inherits option attributes.

### NativeSelectOptGroup
- Inherits optgroup attributes.

## Changelog

### v1.1.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v1.1.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.
- Native Select follows Astro and HTML option-selection semantics. Omitting a value selects the
first option naturally; the legacy React-style `defaultValue` prop is no longer used.

### v1.0.1

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.16.0

---

Source: [https://starwind.dev/docs/components/navigation-menu/](https://starwind.dev/docs/components/navigation-menu/) · [Markdown](https://starwind.dev/docs/components/navigation-menu.md)

# Navigation Menu

Navigation Menu provides Runtime-backed navigation disclosure, focus management, and floating
content positioning.

NavigationMenu,
NavigationMenuContent,
NavigationMenuItem,
NavigationMenuLink,
NavigationMenuList,
NavigationMenuTrigger,
navigationMenuTriggerStyle,
} from "@/components/starwind/navigation-menu";

export const components = [
{
title: "Alert Dialog",
href: "/docs/components/alert-dialog/",
description:
  "A modal dialog that interrupts the user with important content and expects a response.",
},
{
title: "Hover Card",
href: "/docs/components/hover-card/",
description: "For sighted users to preview content available behind a link.",
},
{
title: "Progress",
href: "/docs/components/progress/",
description: "Displays an indicator showing the completion progress of a task.",
},
{
title: "Scroll Area",
href: "/docs/components/scroll-area/",
description: "Augments native scroll functionality for custom, cross-browser styling.",
},
{
title: "Tabs",
href: "/docs/components/tabs/",
description: "A set of layered sections of content displayed one at a time.",
},
{
title: "Tooltip",
href: "/docs/components/tooltip/",
description: "A popup that provides information when an element is focused or hovered.",
},
];

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@/components/starwind/navigation-menu";
import AlertCircle from "@tabler/icons/outline/alert-circle.svg";
import CircleCheck from "@tabler/icons/outline/circle-check.svg";
import CircleDashed from "@tabler/icons/outline/circle-dashed.svg";

const components = [
  {
    title: "Alert Dialog",
    href: "/docs/components/alert-dialog/",
    description:
      "A modal dialog that interrupts the user with important content and expects a response.",
  },
  {
    title: "Hover Card",
    href: "/docs/components/hover-card/",
    description: "For sighted users to preview content available behind a link.",
  },
  {
    title: "Progress",
    href: "/docs/components/progress/",
    description: "Displays an indicator showing the completion progress of a task.",
  },
  {
    title: "Scroll Area",
    href: "/docs/components/scroll-area/",
    description: "Augments native scroll functionality for custom, cross-browser styling.",
  },
  {
    title: "Tabs",
    href: "/docs/components/tabs/",
    description: "A set of layered sections of content displayed one at a time.",
  },
  {
    title: "Tooltip",
    href: "/docs/components/tooltip/",
    description: "A popup that provides information when an element is focused or hovered.",
  },
];
---

<NavigationMenu size="md" aria-label="Documentation navigation">
  <NavigationMenuList>
    <NavigationMenuItem value="getting-started">
      <NavigationMenuTrigger>Getting started</NavigationMenuTrigger>
      <NavigationMenuContent>
        <ul class="w-108">
          <li>
            <NavigationMenuLink href="/docs/getting-started/introduction/">
              <div class="flex flex-col gap-1.5">
                <div class="leading-none font-medium">Introduction</div>
                <div class="text-muted-foreground line-clamp-2">
                  Reusable components built with Tailwind CSS.
                </div>
              </div>
            </NavigationMenuLink>
          </li>
          <li>
            <NavigationMenuLink href="/docs/getting-started/installation/">
              <div class="flex flex-col gap-1.5">
                <div class="leading-none font-medium">Installation</div>
                <div class="text-muted-foreground line-clamp-2">
                  How to install dependencies and structure your app.
                </div>
              </div>
            </NavigationMenuLink>
          </li>
          <li>
            <NavigationMenuLink href="/docs/getting-started/theming/">
              <div class="flex flex-col gap-1.5">
                <div class="leading-none font-medium">Theming</div>
                <div class="text-muted-foreground line-clamp-2">
                  Customize colors, typography, and design tokens.
                </div>
              </div>
            </NavigationMenuLink>
          </li>
        </ul>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem value="components" class="hidden md:flex">
      <NavigationMenuTrigger>Components</NavigationMenuTrigger>
      <NavigationMenuContent>
        <ul class="grid w-[500px] gap-2 md:w-[600px] md:grid-cols-2 lg:w-[700px]">
          {components.map((component) => (
            <li>
              <NavigationMenuLink href={component.href}>
                <div class="flex flex-col gap-1.5">
                  <div class="leading-none font-medium">{component.title}</div>
                  <div class="text-muted-foreground line-clamp-2">
                    {component.description}
                  </div>
                </div>
              </NavigationMenuLink>
            </li>
          ))}
        </ul>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem value="status">
      <NavigationMenuTrigger>With icon</NavigationMenuTrigger>
      <NavigationMenuContent>
        <ul class="grid w-[240px]">
          <li>
            <NavigationMenuLink href="#backlog" class="flex-row items-center gap-2">
              <AlertCircle />Backlog
            </NavigationMenuLink>
            <NavigationMenuLink href="#to-do" class="flex-row items-center gap-2">
              <CircleDashed />To Do
            </NavigationMenuLink>
            <NavigationMenuLink href="#done" class="flex-row items-center gap-2">
              <CircleCheck />Done
            </NavigationMenuLink>
          </li>
        </ul>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="/docs/" class={navigationMenuTriggerStyle()}>
        Docs
      </NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```
  </div>
  <div slot="react">
```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@/components/starwind/navigation-menu";
import {
  IconAlertCircle as AlertCircle,
  IconCircleCheck as CircleCheck,
  IconCircleDashed as CircleDashed,
} from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <NavigationMenu size="md" aria-label="Documentation navigation">
        <NavigationMenuList>
          <NavigationMenuItem value="getting-started">
            <NavigationMenuTrigger>Getting started</NavigationMenuTrigger>
            <NavigationMenuContent>
              <ul className="w-108">
                <li>
                  <NavigationMenuLink href="/docs/getting-started/introduction/">
                    <div className="flex flex-col gap-1.5">
                      <div className="leading-none font-medium">Introduction</div>
                      <div className="text-muted-foreground line-clamp-2">
                        Reusable components built with Tailwind CSS.
                      </div>
                    </div>
                  </NavigationMenuLink>
                </li>
                <li>
                  <NavigationMenuLink href="/docs/getting-started/installation/">
                    <div className="flex flex-col gap-1.5">
                      <div className="leading-none font-medium">Installation</div>
                      <div className="text-muted-foreground line-clamp-2">
                        How to install dependencies and structure your app.
                      </div>
                    </div>
                  </NavigationMenuLink>
                </li>
                <li>
                  <NavigationMenuLink href="/docs/getting-started/theming/">
                    <div className="flex flex-col gap-1.5">
                      <div className="leading-none font-medium">Theming</div>
                      <div className="text-muted-foreground line-clamp-2">
                        Customize colors, typography, and design tokens.
                      </div>
                    </div>
                  </NavigationMenuLink>
                </li>
              </ul>
            </NavigationMenuContent>
          </NavigationMenuItem>
          <NavigationMenuItem value="components" className="hidden md:flex">
            <NavigationMenuTrigger>Components</NavigationMenuTrigger>
            <NavigationMenuContent>
              <ul className="grid w-[500px] gap-2 md:w-[600px] md:grid-cols-2 lg:w-[700px]">
                {components.map((component) => (
                  <li key={`${component.href}-${component.title}`}>
                    <NavigationMenuLink href={component.href}>
                      <div className="flex flex-col gap-1.5">
                        <div className="leading-none font-medium">{component.title}</div>
                        <div className="text-muted-foreground line-clamp-2">
                          {component.description}
                        </div>
                      </div>
                    </NavigationMenuLink>
                  </li>
                ))}
              </ul>
            </NavigationMenuContent>
          </NavigationMenuItem>
          <NavigationMenuItem value="status">
            <NavigationMenuTrigger>With icon</NavigationMenuTrigger>
            <NavigationMenuContent>
              <ul className="grid w-[240px]">
                <li>
                  <NavigationMenuLink href="#backlog" className="flex-row items-center gap-2">
                    <AlertCircle />Backlog
                  </NavigationMenuLink>
                  <NavigationMenuLink href="#to-do" className="flex-row items-center gap-2">
                    <CircleDashed />To Do
                  </NavigationMenuLink>
                  <NavigationMenuLink href="#done" className="flex-row items-center gap-2">
                    <CircleCheck />Done
                  </NavigationMenuLink>
                </li>
              </ul>
            </NavigationMenuContent>
          </NavigationMenuItem>
          <NavigationMenuItem>
            <NavigationMenuLink href="/docs/" className={navigationMenuTriggerStyle()}>
              Docs
            </NavigationMenuLink>
          </NavigationMenuItem>
        </NavigationMenuList>
      </NavigationMenu>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add navigation-menu
```

## Usage

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
---
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from "@/components/starwind/navigation-menu";
---
```
</div>
<div slot="react">
```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from "@/components/starwind/navigation-menu";
```
</div>
</FrameworkCodeSwitcher>

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem value="item-one">
      <NavigationMenuTrigger>Item One</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/docs/">Link</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```
</div>
<div slot="react">
```tsx
import { NavigationMenu, NavigationMenuContent, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger } from "@/components/starwind/navigation-menu";

export function Example() {
  return (
    <>
      <NavigationMenu>
        <NavigationMenuList>
          <NavigationMenuItem value="item-one">
            <NavigationMenuTrigger>Item One</NavigationMenuTrigger>
            <NavigationMenuContent>
              <NavigationMenuLink href="/docs/">Link</NavigationMenuLink>
            </NavigationMenuContent>
          </NavigationMenuItem>
        </NavigationMenuList>
      </NavigationMenu>
    </>
  );
}
```
</div>
</FrameworkCodeSwitcher>

### Sizes

`NavigationMenu` defaults to `size="md"`. Set `size` once to keep native triggers, List spacing,
trigger-style Links, and portaled content aligned. Use `contentSize` only when the shared popup
should intentionally use a different size.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import AlertCircle from "@tabler/icons/outline/alert-circle.svg";
import CircleCheck from "@tabler/icons/outline/circle-check.svg";
import CircleDashed from "@tabler/icons/outline/circle-dashed.svg";
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@/components/starwind/navigation-menu";

const componentLinks = [
  {
    title: "Alert Dialog",
    href: "/docs/components/alert-dialog/",
    description: "A modal dialog that asks for a response.",
  },
  {
    title: "Hover Card",
    href: "/docs/components/hover-card/",
    description: "Preview content available behind a link.",
  },
];
---

<div class="grid gap-6">
  <div class="space-y-3">
    <div class="text-muted-foreground text-sm font-medium">Small (sm)</div>
    <NavigationMenu size="sm" aria-label="Small documentation navigation">
      <NavigationMenuList>
        <NavigationMenuItem value="small-getting-started">
          <NavigationMenuTrigger>Getting started</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul class="w-96">
              <li>
                <NavigationMenuLink href="/docs/getting-started/introduction/">
                  <div class="flex flex-col gap-1 text-sm">
                    <div class="leading-none font-medium">Introduction</div>
                    <div class="text-muted-foreground line-clamp-2">
                      Reusable components built with Tailwind CSS.
                    </div>
                  </div>
                </NavigationMenuLink>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem value="small-components" class="hidden md:flex">
          <NavigationMenuTrigger>Components</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul class="grid w-[400px] gap-2 md:w-[500px] md:grid-cols-2 lg:w-[600px]">
              {componentLinks.map((component) => (
                <li>
                  <NavigationMenuLink href={component.href}>
                    <div class="flex flex-col gap-1 text-sm">
                      <div class="leading-none font-medium">{component.title}</div>
                      <div class="text-muted-foreground line-clamp-2">
                        {component.description}
                      </div>
                    </div>
                  </NavigationMenuLink>
                </li>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem value="small-status">
          <NavigationMenuTrigger>With icon</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul class="grid w-[200px]">
              <li>
                <NavigationMenuLink href="#small-backlog" class="flex-row items-center gap-2">
                  <AlertCircle />Backlog
                </NavigationMenuLink>
                <NavigationMenuLink href="#small-to-do" class="flex-row items-center gap-2">
                  <CircleDashed />To Do
                </NavigationMenuLink>
                <NavigationMenuLink href="#small-done" class="flex-row items-center gap-2">
                  <CircleCheck />Done
                </NavigationMenuLink>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="/docs/" class={navigationMenuTriggerStyle()}>
            Docs
          </NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  </div>

<div class="space-y-3">
    <div class="text-muted-foreground text-sm font-medium">Medium (md)</div>
    <NavigationMenu size="md" aria-label="Medium documentation navigation">
      <NavigationMenuList>
        <NavigationMenuItem value="medium-getting-started">
          <NavigationMenuTrigger>Getting started</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul class="w-108">
              <li>
                <NavigationMenuLink href="/docs/getting-started/introduction/">
                  <div class="flex flex-col gap-1.5">
                    <div class="leading-none font-medium">Introduction</div>
                    <div class="text-muted-foreground line-clamp-2">
                      Reusable components built with Tailwind CSS.
                    </div>
                  </div>
                </NavigationMenuLink>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem value="medium-components" class="hidden md:flex">
          <NavigationMenuTrigger>Components</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul class="grid w-[500px] gap-2 md:w-[600px] md:grid-cols-2 lg:w-[700px]">
              {componentLinks.map((component) => (
                <li>
                  <NavigationMenuLink href={component.href}>
                    <div class="flex flex-col gap-1.5">
                      <div class="leading-none font-medium">{component.title}</div>
                      <div class="text-muted-foreground line-clamp-2">
                        {component.description}
                      </div>
                    </div>
                  </NavigationMenuLink>
                </li>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem value="medium-status">
          <NavigationMenuTrigger>With icon</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul class="grid w-[240px]">
              <li>
                <NavigationMenuLink href="#medium-backlog" class="flex-row items-center gap-2">
                  <AlertCircle />Backlog
                </NavigationMenuLink>
                <NavigationMenuLink href="#medium-to-do" class="flex-row items-center gap-2">
                  <CircleDashed />To Do
                </NavigationMenuLink>
                <NavigationMenuLink href="#medium-done" class="flex-row items-center gap-2">
                  <CircleCheck />Done
                </NavigationMenuLink>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="/docs/" class={navigationMenuTriggerStyle()}>
            Docs
          </NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  </div>
</div>
```
  </div>
  <div slot="react">
```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@/components/starwind/navigation-menu";
import { IconAlertCircle, IconCircleCheck, IconCircleDashed } from "@tabler/icons-react";

export function Example() {
  return (
    <div className="grid gap-6">
      <div className="space-y-3">
        <div className="text-muted-foreground text-sm font-medium">Small (sm)</div>
        <NavigationMenu size="sm" aria-label="Small documentation navigation">
          <NavigationMenuList>
            <NavigationMenuItem value="small-getting-started">
              <NavigationMenuTrigger>Getting started</NavigationMenuTrigger>
              <NavigationMenuContent>
                <ul className="w-96">
                  <li>
                    <NavigationMenuLink href="/docs/getting-started/introduction/">
                      <div className="flex flex-col gap-1 text-sm">
                        <div className="leading-none font-medium">Introduction</div>
                        <div className="text-muted-foreground line-clamp-2">
                          Reusable components built with Tailwind CSS.
                        </div>
                      </div>
                    </NavigationMenuLink>
                  </li>
                </ul>
              </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem value="small-components" className="hidden md:flex">
              <NavigationMenuTrigger>Components</NavigationMenuTrigger>
              <NavigationMenuContent>
                <ul className="grid w-[400px] gap-2 md:w-[500px] md:grid-cols-2 lg:w-[600px]">
                  {componentLinks.map((component) => (
                    <li key={component.href}>
                      <NavigationMenuLink href={component.href}>
                        <div className="flex flex-col gap-1 text-sm">
                          <div className="leading-none font-medium">{component.title}</div>
                          <div className="text-muted-foreground line-clamp-2">
                            {component.description}
                          </div>
                        </div>
                      </NavigationMenuLink>
                    </li>
                  ))}
                </ul>
              </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem value="small-status">
              <NavigationMenuTrigger>With icon</NavigationMenuTrigger>
              <NavigationMenuContent>
                <ul className="grid w-[200px]">
                  <li>
                    <NavigationMenuLink href="#small-backlog" className="flex-row items-center gap-2">
                      <IconAlertCircle />Backlog
                    </NavigationMenuLink>
                    <NavigationMenuLink href="#small-to-do" className="flex-row items-center gap-2">
                      <IconCircleDashed />To Do
                    </NavigationMenuLink>
                    <NavigationMenuLink href="#small-done" className="flex-row items-center gap-2">
                      <IconCircleCheck />Done
                    </NavigationMenuLink>
                  </li>
                </ul>
              </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem>
              <NavigationMenuLink href="/docs/" className={navigationMenuTriggerStyle()}>
                Docs
              </NavigationMenuLink>
            </NavigationMenuItem>
          </NavigationMenuList>
        </NavigationMenu>
      </div>

<div className="space-y-3">
        <div className="text-muted-foreground text-sm font-medium">Medium (md)</div>
        <NavigationMenu size="md" aria-label="Medium documentation navigation">
          <NavigationMenuList>
            <NavigationMenuItem value="medium-getting-started">
              <NavigationMenuTrigger>Getting started</NavigationMenuTrigger>
              <NavigationMenuContent>
                <ul className="w-108">
                  <li>
                    <NavigationMenuLink href="/docs/getting-started/introduction/">
                      <div className="flex flex-col gap-1.5">
                        <div className="leading-none font-medium">Introduction</div>
                        <div className="text-muted-foreground line-clamp-2">
                          Reusable components built with Tailwind CSS.
                        </div>
                      </div>
                    </NavigationMenuLink>
                  </li>
                </ul>
              </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem value="medium-components" className="hidden md:flex">
              <NavigationMenuTrigger>Components</NavigationMenuTrigger>
              <NavigationMenuContent>
                <ul className="grid w-[500px] gap-2 md:w-[600px] md:grid-cols-2 lg:w-[700px]">
                  {componentLinks.map((component) => (
                    <li key={component.href}>
                      <NavigationMenuLink href={component.href}>
                        <div className="flex flex-col gap-1.5">
                          <div className="leading-none font-medium">{component.title}</div>
                          <div className="text-muted-foreground line-clamp-2">
                            {component.description}
                          </div>
                        </div>
                      </NavigationMenuLink>
                    </li>
                  ))}
                </ul>
              </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem value="medium-status">
              <NavigationMenuTrigger>With icon</NavigationMenuTrigger>
              <NavigationMenuContent>
                <ul className="grid w-[240px]">
                  <li>
                    <NavigationMenuLink href="#medium-backlog" className="flex-row items-center gap-2">
                      <IconAlertCircle />Backlog
                    </NavigationMenuLink>
                    <NavigationMenuLink href="#medium-to-do" className="flex-row items-center gap-2">
                      <IconCircleDashed />To Do
                    </NavigationMenuLink>
                    <NavigationMenuLink href="#medium-done" className="flex-row items-center gap-2">
                      <IconCircleCheck />Done
                    </NavigationMenuLink>
                  </li>
                </ul>
              </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem>
              <NavigationMenuLink href="/docs/" className={navigationMenuTriggerStyle()}>
                Docs
              </NavigationMenuLink>
            </NavigationMenuItem>
          </NavigationMenuList>
        </NavigationMenu>
      </div>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Custom triggers

Native `NavigationMenuTrigger` elements merge ordinary `class` customization through their full
recipe. With `asChild`, the child instead owns its complete appearance and markup; Navigation Menu
adds behavior, accessibility/state attributes, and the Trigger's consumer-provided class.

## Composition

Use the following composition to build a `NavigationMenu`:

```text
NavigationMenu
├── NavigationMenuList
│   ├── NavigationMenuItem
│   │   ├── NavigationMenuTrigger
│   │   └── NavigationMenuContent
│   │       ├── NavigationMenuLink
│   │       └── NavigationMenuLink
│   └── NavigationMenuItem
│       └── NavigationMenuLink
└── NavigationMenuIndicator
```

## API Reference
### NavigationMenu
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | No | `"start"` | Wrapper prop | Aligns the component within its available axis. |
| `alignOffset` | `number` | No | `0` | Wrapper prop | Offsets the component from its selected alignment in pixels. |
| `avoidCollisions` | `boolean` | No | `true` | Wrapper prop | Repositions floating content to keep it inside the collision boundary. |
| `collisionPadding` | `number` | No | `8` | Wrapper prop | Sets the minimum space retained around a collision boundary. |
| `contentSize` | `"sm" \| "md"` | No | `size` | Wrapper prop | Sets the independently portaled popup content size and defaults to the resolved Navigation Menu size. |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | No | `"bottom"` | Wrapper prop | Selects the preferred side for floating content. |
| `sideOffset` | `number` | No | `8` | Wrapper prop | Sets the distance in pixels between floating content and its anchor. |
| `size` | `"sm" \| "md"` | No | `"md"` | Wrapper prop | Sets the visual size of native styled triggers, List spacing, indicators, and top-level Links using navigationMenuTriggerStyle(). |
- Inherits nav attributes. Omits `defaultValue`, `onChange`, and `value`.

### NavigationMenuList
- Inherits ul attributes.

### NavigationMenuItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | `string` | No | - | Wrapper prop | Controls or identifies the component value. |
- Inherits li attributes.

### NavigationMenuTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Primitive override | Delegates markup and complete visual ownership to the child while retaining Navigation Menu behavior and accessibility wiring. |
| `closeDelay` | `number` | No | - | Primitive override | Sets the delay in milliseconds before closing. |
| `iconClass` | `string` | No | - | Wrapper prop | Adds classes to the component's generated icon. |
| `openDelay` | `number` | No | - | Primitive override | Sets the delay in milliseconds before opening. |
| `showIcon` | `boolean` | No | `true` | Wrapper prop | Shows the component's generated icon. |
- Inherits button attributes.

### NavigationMenuIndicator
- Inherits span attributes.

### NavigationMenuContent
- Inherits div attributes.

### NavigationMenuLink
- Inherits a attributes.

### NavigationMenuPositioner
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `sideOffset` | `number` | No | `8` | Primitive override | Sets the distance in pixels between floating content and its anchor. |
| `size` | `"sm" \| "md"` | No | `"md"` | Wrapper prop | Sets the popup content size when rendering NavigationMenuPositioner directly. |
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Navigation Menu Primitive](/docs/primitives/navigation-menu/)
- Runtime factory: [`createNavigationMenu`](/docs/runtime/#create-navigation-menu) from `@starwind-ui/runtime/navigation-menu`

## Changelog

### v1.1.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v1.1.0

- Added root `sm` and `md` sizing plus independent `contentSize` control for the shared
portaled popup. Omitted `contentSize` follows the resolved root `size`.
- Corrected styled `NavigationMenuTrigger asChild` ownership: the composed child now keeps its own
complete appearance and markup. Style and size the child directly, and add any desired icon
inside it; Navigation Menu still supplies behavior and accessibility wiring.

### v1.0.0

- Added the Runtime-backed Navigation Menu with keyboard navigation and shared viewport behavior.
- See the [Navigation Menu Primitive](/docs/primitives/navigation-menu/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/pagination/](https://starwind.dev/docs/components/pagination/) · [Markdown](https://starwind.dev/docs/components/pagination.md)

# Pagination

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  Pagination,
  PaginationEllipsis,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/starwind/pagination";
---
<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="#">Prev</PaginationPrevious>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#" isActive>2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">3</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="#">Next</PaginationNext>
    </PaginationItem>
  </PaginationContent>
</Pagination>
```
  </div>
  <div slot="react">
```tsx
import {
  Pagination,
  PaginationEllipsis,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/starwind/pagination";

export function Example() {
  return (
    <>
      <Pagination>
        <PaginationContent>
          <PaginationItem>
            <PaginationPrevious href="#">Prev</PaginationPrevious>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#">1</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#" isActive>2</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#">3</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationEllipsis />
          </PaginationItem>
          <PaginationItem>
            <PaginationNext href="#">Next</PaginationNext>
          </PaginationItem>
        </PaginationContent>
      </Pagination>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add pagination
```

## Usage

### General Notes

The basic pagination component includes previous/next buttons and numbered pages.

> **Tip:** Use the `isActive` prop on `<PaginationLink>` to highlight the current page.

### Sizes

Set `size="sm"`, `size="md"` (the default), or `size="lg"` once on `Pagination`. The root
publishes the resolved size through `data-size`, and every link, navigation control, and ellipsis
uses that shared visual scale.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
  PaginationEllipsis,
} from "@/components/starwind/pagination";
---

<section class="mx-auto mt-10 max-w-lg">
  <Pagination size="lg">
    <PaginationContent>
      <PaginationItem>
        <PaginationPrevious href="#">Prev</PaginationPrevious>
      </PaginationItem>
      <PaginationItem>
        <PaginationLink href="#">1</PaginationLink>
      </PaginationItem>
      <PaginationItem>
        <PaginationLink href="#" isActive>2</PaginationLink>
      </PaginationItem>
      <PaginationItem>
        <PaginationLink href="#">3</PaginationLink>
      </PaginationItem>
      <PaginationItem>
        <PaginationEllipsis />
      </PaginationItem>
      <PaginationItem>
        <PaginationNext href="#">Next</PaginationNext>
      </PaginationItem>
    </PaginationContent>
  </Pagination>
</section>
```
  </div>
  <div slot="react">
```tsx
import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
  PaginationEllipsis,
} from "@/components/starwind/pagination";

export function Example() {
  return (
    <>
      <section className="mx-auto mt-10 max-w-lg">
        <Pagination size="sm">
          <PaginationContent>
            <PaginationItem>
              <PaginationPrevious href="#">Prev</PaginationPrevious>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#">1</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#" isActive>2</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#">3</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationEllipsis />
            </PaginationItem>
            <PaginationItem>
              <PaginationNext href="#">Next</PaginationNext>
            </PaginationItem>
          </PaginationContent>
        </Pagination>
      </section>

### Size migration

| Before | After |
| --- | --- |
| `<PaginationLink size="icon-sm" />` | `<Pagination size="sm"><PaginationLink /></Pagination>` |
| `<PaginationPrevious size="lg" />` | `<Pagination size="lg"><PaginationPrevious /></Pagination>` |

## API Reference
### Pagination
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Wrapper prop | Selects the component's visual size. |
- Inherits nav attributes.

### PaginationContent
- Inherits ul attributes.

### PaginationItem
- Inherits li attributes.

### PaginationLink
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `isActive` | `boolean` | No | - | Wrapper prop | Applies the active visual state. |
- Inherits Button props. Omits `as`, `ref`, and `variant`.

### PaginationPrevious
- Inherits PaginationLink props.

### PaginationNext
- Inherits PaginationLink props.

### PaginationEllipsis
- Inherits span attributes.

## Changelog

### v4.0.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v4.0.0

- Moved `size` ownership to `Pagination`; remove `size` from `PaginationLink`,
`PaginationPrevious`, `PaginationNext`, and `PaginationEllipsis`.
- Migration: `<PaginationLink size="icon-sm" />` becomes
`<Pagination size="sm"><PaginationLink /></Pagination>`.

### v3.1.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v3.0.4

- Refactor tailwind variants functions into separate `variants.ts` file

### v3.0.2

- add size prop to `PaginationEllipsis`
- Adjust `PaginationNext` and `PaginationPrevious` to use button variant props for sizes

### v3.0.1

- Add named slot "icon" to `PaginationEllipsis` to enable easy icon swapping, and a default slot for the `sr-only` label
- Add named slot "icon" to `PaginationNext` and `Pagination Previous` to enable easy icon swapping

### v3.0.0

- Now requires the starwind button component installed to make use of the button variants for `PaginationLink`

### v2.1.0

- Add `data-slot` attribute to enable global styling updates

### v2.0.1

- Add eslint comments to disable "no-explicit-any" when using Astro special syntax to require a child element

### v2.0.0

- `tailwind-variants` now implemented. This uses `tailwind-merge` under the hood to merge Tailwind classes without style conflicts.
- Removed `radius` prop now that classes like "rounded-full" can be passed to the components to override, taking advantage of `tailwind-variants`

---

Source: [https://starwind.dev/docs/components/popover/](https://starwind.dev/docs/components/popover/) · [Markdown](https://starwind.dev/docs/components/popover.md)

# Popover

Popover,
PopoverContent,
PopoverDescription,
PopoverHeader,
PopoverTitle,
PopoverTrigger,
} from "@/components/starwind/popover";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import { Input } from "@/components/starwind/input";
import { Label } from "@/components/starwind/label";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/starwind/popover";
---

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">Open popover</Button>
  </PopoverTrigger>
  <PopoverContent class="w-80">
    <PopoverHeader>
      <PopoverTitle>Dimensions</PopoverTitle>
      <PopoverDescription>
        Set the dimensions for the layer.
      </PopoverDescription>
    </PopoverHeader>
    <div class="grid gap-2 px-0.5">
      <div class="grid grid-cols-3 items-center gap-3">
        <Label for="popover-width">Width</Label>
        <Input id="popover-width" value="100%" class="col-span-2 h-8" />
      </div>
      <div class="grid grid-cols-3 items-center gap-3">
        <Label for="popover-max-width">Max. width</Label>
        <Input id="popover-max-width" value="300px" class="col-span-2 h-8" />
      </div>
      <div class="grid grid-cols-3 items-center gap-3">
        <Label for="popover-height">Height</Label>
        <Input id="popover-height" value="25px" class="col-span-2 h-8" />
      </div>
      <div class="grid grid-cols-3 items-center gap-3">
        <Label for="popover-max-height">Max. height</Label>
        <Input id="popover-max-height" value="none" class="col-span-2 h-8" />
      </div>
    </div>
  </PopoverContent>
</Popover>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import { Input } from "@/components/starwind/input";
import { Label } from "@/components/starwind/label";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/starwind/popover";

export function Example() {
  return (
    <>
      <Popover>
        <PopoverTrigger asChild>
          <Button variant="outline">Open popover</Button>
        </PopoverTrigger>
        <PopoverContent className="w-80">
          <PopoverHeader>
            <PopoverTitle>Dimensions</PopoverTitle>
                <PopoverDescription>
                  Set the dimensions for the layer.
                </PopoverDescription>
          </PopoverHeader>
          <div className="grid gap-2 px-0.5">
            <div className="grid grid-cols-3 items-center gap-3">
              <Label htmlFor="popover-width">Width</Label>
              <Input id="popover-width" defaultValue="100%" className="col-span-2 h-8" />
            </div>
            <div className="grid grid-cols-3 items-center gap-3">
              <Label htmlFor="popover-max-width">Max. width</Label>
              <Input id="popover-max-width" defaultValue="300px" className="col-span-2 h-8" />
            </div>
            <div className="grid grid-cols-3 items-center gap-3">
              <Label htmlFor="popover-height">Height</Label>
              <Input id="popover-height" defaultValue="25px" className="col-span-2 h-8" />
            </div>
            <div className="grid grid-cols-3 items-center gap-3">
              <Label htmlFor="popover-max-height">Max. height</Label>
              <Input id="popover-max-height" defaultValue="none" className="col-span-2 h-8" />
            </div>
          </div>
        </PopoverContent>
      </Popover>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add popover
```

## Usage

### General Notes

Popovers are ideal for showing contextual content, settings, and quick actions without leaving the current page.

The essential components are `Popover`, `PopoverTrigger`, and `PopoverContent`. Use `PopoverHeader`, `PopoverTitle`, and `PopoverDescription` to create a consistent content structure.

### Hover Open

Enable hover behavior with `openOnHover`. Use `closeDelay` to control how long the popover stays open after the pointer leaves.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/starwind/popover";
---

<Popover openOnHover closeDelay={120}>
  <PopoverTrigger asChild>
    <Button variant="outline">Quick close</Button>
  </PopoverTrigger>
  <PopoverContent class="w-56">
    <PopoverHeader>
      <PopoverTitle>Fast close delay</PopoverTitle>
      <PopoverDescription>
        This popover closes quickly with `closeDelay` set to 120ms.
      </PopoverDescription>
    </PopoverHeader>
  </PopoverContent>
</Popover>

<Popover openOnHover closeDelay={500}>
  <PopoverTrigger asChild>
    <Button variant="outline">Slow close</Button>
  </PopoverTrigger>
  <PopoverContent class="w-56">
    <PopoverHeader>
      <PopoverTitle>Longer close delay</PopoverTitle>
      <PopoverDescription>
        This popover remains open longer with `closeDelay` set to 500ms.
      </PopoverDescription>
    </PopoverHeader>
  </PopoverContent>
</Popover>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/starwind/popover";

export function Example() {
  return (
    <>
      <Popover openOnHover closeDelay={120}>
        <PopoverTrigger asChild>
          <Button variant="outline">Quick close</Button>
        </PopoverTrigger>
        <PopoverContent className="w-56">
          <PopoverHeader>
            <PopoverTitle>Fast close delay</PopoverTitle>
            <PopoverDescription>
              This popover closes quickly with `closeDelay` set to 120ms.
            </PopoverDescription>
          </PopoverHeader>
        </PopoverContent>
      </Popover>

<Popover openOnHover closeDelay={500}>
        <PopoverTrigger asChild>
          <Button variant="outline">Slow close</Button>
        </PopoverTrigger>
        <PopoverContent className="w-56">
          <PopoverHeader>
            <PopoverTitle>Longer close delay</PopoverTitle>
            <PopoverDescription>
              This popover remains open longer with `closeDelay` set to 500ms.
            </PopoverDescription>
          </PopoverHeader>
        </PopoverContent>
      </Popover>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Nested Popovers

Nested popovers work without immediately closing the parent popover while you interact with child content.

<Popover>
  <PopoverTrigger asChild>
    <Button>Nested popover</Button>
  </PopoverTrigger>
  <PopoverContent class="w-72" align="start">
    <PopoverHeader>
      <PopoverTitle>Parent popover</PopoverTitle>
      <PopoverDescription>
        Open the nested popover below to verify nested interaction behavior.
      </PopoverDescription>
    </PopoverHeader>
    <div class="mt-2">
      <Popover>
        <PopoverTrigger asChild>
          <Button variant="outline">Open child</Button>
        </PopoverTrigger>
        <PopoverContent side="right" align="start" class="w-64">
          <PopoverHeader>
            <PopoverTitle>Child popover</PopoverTitle>
            <PopoverDescription>
              These will stay nicely positioned even as the viewport shrinks or expands.
            </PopoverDescription>
          </PopoverHeader>
        </PopoverContent>
      </Popover>
    </div>
  </PopoverContent>
</Popover>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/starwind/popover";

export function Example() {
  return (
    <>
      <Popover>
        <PopoverTrigger asChild>
          <Button>Nested popover</Button>
        </PopoverTrigger>
        <PopoverContent className="w-72" align="start">
          <PopoverHeader>
            <PopoverTitle>Parent popover</PopoverTitle>
            <PopoverDescription>
              Open the nested popover below to verify nested interaction behavior.
            </PopoverDescription>
          </PopoverHeader>
          <div className="mt-2">
            <Popover>
              <PopoverTrigger asChild>
                <Button variant="outline">Open child</Button>
              </PopoverTrigger>
              <PopoverContent side="right" align="start" className="w-64">
                <PopoverHeader>
                  <PopoverTitle>Child popover</PopoverTitle>
                  <PopoverDescription>
                    These will stay nicely positioned even as the viewport shrinks or expands.
                  </PopoverDescription>
                </PopoverHeader>
              </PopoverContent>
            </Popover>
          </div>
        </PopoverContent>
      </Popover>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Align: start, center, end

Use the `align` prop on `PopoverContent` to control horizontal alignment relative to the trigger.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/starwind/popover";
---

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">Start</Button>
  </PopoverTrigger>
  <PopoverContent align="start" class="w-40">
    Aligned to start.
  </PopoverContent>
</Popover>

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">Center</Button>
  </PopoverTrigger>
  <PopoverContent align="center" class="w-40">
    Aligned to center.
  </PopoverContent>
</Popover>

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">End</Button>
  </PopoverTrigger>
  <PopoverContent align="end" class="w-40">
    Aligned to end.
  </PopoverContent>
</Popover>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/starwind/popover";

export function Example() {
  return (
    <>
      <Popover>
        <PopoverTrigger asChild>
          <Button variant="outline">Start</Button>
        </PopoverTrigger>
        <PopoverContent align="start" className="w-40">
          Aligned to start.
        </PopoverContent>
      </Popover>

<Popover>
        <PopoverTrigger asChild>
          <Button variant="outline">Center</Button>
        </PopoverTrigger>
        <PopoverContent align="center" className="w-40">
          Aligned to center.
        </PopoverContent>
      </Popover>

<Popover>
        <PopoverTrigger asChild>
          <Button variant="outline">End</Button>
        </PopoverTrigger>
        <PopoverContent align="end" className="w-40">
          Aligned to end.
        </PopoverContent>
      </Popover>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Side and sideOffset

Position content with `side` and add spacing from the trigger with `sideOffset`.

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" class="w-full">Top</Button>
  </PopoverTrigger>
  <PopoverContent side="top" sideOffset={12} class="w-44">
    side="top" with sideOffset=12 and a quicker animation.
  </PopoverContent>
</Popover>

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" class="w-full">Right</Button>
  </PopoverTrigger>
  <PopoverContent side="right" align="start" sideOffset={16} class="w-44">
    side="right" + align="start".
  </PopoverContent>
</Popover>

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" class="w-full">Bottom</Button>
  </PopoverTrigger>
  <PopoverContent side="bottom" align="end" sideOffset={8} class="w-44">
    side="bottom" + align="end".
  </PopoverContent>
</Popover>

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" class="w-full">Left</Button>
  </PopoverTrigger>
  <PopoverContent side="left" sideOffset={14} class="w-44">
    side="left" with a longer animation duration.
  </PopoverContent>
</Popover>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/starwind/popover";

export function Example() {
  return (
    <>
      <Popover>
        <PopoverTrigger asChild>
          <Button variant="outline" className="w-full">Top</Button>
        </PopoverTrigger>
        <PopoverContent side="top" sideOffset={12} className="w-44">
          side="top" with sideOffset=12 and a quicker animation.
        </PopoverContent>
      </Popover>

<Popover>
        <PopoverTrigger asChild>
          <Button variant="outline" className="w-full">Right</Button>
        </PopoverTrigger>
        <PopoverContent side="right" align="start" sideOffset={16} className="w-44">
          side="right" + align="start".
        </PopoverContent>
      </Popover>

<Popover>
        <PopoverTrigger asChild>
          <Button variant="outline" className="w-full">Bottom</Button>
        </PopoverTrigger>
        <PopoverContent side="bottom" align="end" sideOffset={8} className="w-44">
          side="bottom" + align="end".
        </PopoverContent>
      </Popover>

<Popover>
        <PopoverTrigger asChild>
          <Button variant="outline" className="w-full">Left</Button>
        </PopoverTrigger>
        <PopoverContent side="left" sideOffset={14} className="w-44">
          side="left" with a longer animation duration.
        </PopoverContent>
      </Popover>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Popover
- Inherits div attributes.

### PopoverTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Primitive override | Merges the component behavior and props into its child element. |
- Inherits button attributes.

### PopoverContent
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `exitMotion` | `"popover" \| "fade"` | No | `"popover"` | Styled variant | Selects the motion treatment used while floating content closes. |
- Inherits div attributes.

### PopoverHeader
- Inherits div attributes.

### PopoverTitle
- Inherits h2 attributes.

### PopoverDescription
- Inherits p attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Popover Primitive](/docs/primitives/popover/)
- Runtime factory: [`createPopover`](/docs/runtime/#create-popover) from `@starwind-ui/runtime/popover`

## Changelog

### v2.0.3

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.0

- Rebuilt Popover on Starwind Runtime for open state, floating placement, dismissal, and nesting.
- See the [Popover Primitive](/docs/primitives/popover/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/progress/](https://starwind.dev/docs/components/progress/) · [Markdown](https://starwind.dev/docs/components/progress.md)

# Progress

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Progress } from "@/components/starwind/progress";
---

<div class="w-full max-w-[400px]">
  <Progress id="demo-progress" value={50} />
</div>
```
  </div>
  <div slot="react">
```tsx
import { Progress } from "@/components/starwind/progress";

export function Example() {
  return (
    <>
      <div className="w-full max-w-[400px]">
        <Progress id="demo-progress" value={50} />
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add progress
```

## Usage

### Variants

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Progress } from "@/components/starwind/progress";
---

<div class="flex flex-col gap-4 w-full max-w-[400px]" slot="preview">
  <Progress id="default" value={60} variant="default" />
  <Progress id="primary" value={60} variant="primary" />
  <Progress id="secondary" value={60} variant="secondary" />
  <Progress id="info" value={60} variant="info" />
  <Progress id="success" value={60} variant="success" />
  <Progress id="warning" value={60} variant="warning" />
  <Progress id="error" value={60} variant="error" />
</div>
```
  </div>
  <div slot="react">
```tsx
import { Progress } from "@/components/starwind/progress";

export function Example() {
  return (
    <>
      <div className="flex flex-col gap-4 w-full max-w-[400px]">
        <Progress id="default" value={60} variant="default" />
        <Progress id="primary" value={60} variant="primary" />
        <Progress id="secondary" value={60} variant="secondary" />
        <Progress id="info" value={60} variant="info" />
        <Progress id="success" value={60} variant="success" />
        <Progress id="warning" value={60} variant="warning" />
        <Progress id="error" value={60} variant="error" />
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Indeterminate

When you need to show a loading state without a specific value, omit the `value` prop to create an indeterminate progress bar.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Progress } from "@/components/starwind/progress";
---

<Progress id="indeterminate" />
```
  </div>
  <div slot="react">
```tsx
import { Progress } from "@/components/starwind/progress";

export function Example() {
  return (
    <>
      <Progress id="indeterminate" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Dynamic Updates

The Progress component can be updated dynamically by changing the `data-value` attribute. This is useful for showing real-time progress like file uploads, form completion, or step-by-step processes.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Progress } from "@/components/starwind/progress";
import { Button } from "@/components/starwind/button";
---

<div class="flex w-full max-w-[400px] flex-col gap-4">
  <h3 class="text-lg font-medium">Interactive Progress Example</h3>

<Button id="toggle-progress" variant="outline">Toggle Progress (25% ⟷ 75%)</Button>
  </div>
</div>

function setupProgressExample() {
    const progressElement = document.getElementById("interactive-progress");
    const toggleButton = document.getElementById("toggle-progress");

if (!progressElement || !toggleButton) return;

toggleButton.addEventListener("click", () => {
      isHighValue = !isHighValue;
      const newValue = isHighValue ? 75 : 25;

progressElement.setAttribute("data-value", String(newValue));
    });
  }

setupProgressExample();
  document.addEventListener("astro:after-swap", setupProgressExample);
</script>
```
  </div>
  <div slot="react">
```tsx
import { useState } from "react";
import { Button } from "@/components/starwind/button";
import { Progress } from "@/components/starwind/progress";

export function Example() {
  const [value, setValue] = useState(25);

return (
    <div className="flex w-full max-w-[400px] flex-col gap-4">
      <h3 className="text-lg font-medium">Interactive Progress Example</h3>
      <div className="space-y-4">
        <Progress value={value} className="w-full" />
        <Button
          variant="outline"
          onClick={() => setValue((current) => (current === 25 ? 75 : 25))}
        >
          Toggle Progress (25% ↔ 75%)
        </Button>
      </div>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Progress
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | `string` | No | - | Wrapper prop | Provides accessible text for the component. |
| `max` | `number` | No | `100` | Wrapper prop | Sets the maximum accepted value. |
| `min` | `number` | No | `0` | Wrapper prop | Sets the minimum accepted value. |
| `value` | `number \| null` | No | `null` | Wrapper prop | Controls or identifies the component value. |
| `variant` | `"default" \| "primary" \| "secondary" \| "info" \| "success" \| "warning" \| "error"` | No | `"default"` | Wrapper prop | Selects the component's visual variant. |
- Inherits div attributes. Omits `value`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Progress Primitive](/docs/primitives/progress/)
- Runtime factory: [`createProgress`](/docs/runtime/#create-progress) from `@starwind-ui/runtime/progress`

## Changelog

### v2.0.3

- Progress indicators now use the neutral `default` color variant when `color` is omitted.

### v2.0.2

- Updated React Runtime state synchronization so canceled proposals stay uncommitted and accepted changes remain aligned.

### v2.0.1

- Normalized reversed, equal, invalid, and non-finite ranges and values consistently across the Astro and React components.
- Prevented transitions between incompatible determinate and indeterminate indicator geometries while preserving determinate value transitions and reduced-motion behavior.

### v2.0.0

- Rebuilt Progress on Starwind Runtime for determinate and indeterminate state.
- See the [Progress Primitive](/docs/primitives/progress/) for the underlying unstyled anatomy and behavior API.

### v1.1.3

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.1.1

- Add `starwind:init` event listener to enable initialization of additional Progress loaded after an initial page load, such as when using server islands

### v1.1.0

- Add `data-slot` attribute to enable global styling updates

### v1.0.0

- Initial release with starwind v1.7.0

---

Source: [https://starwind.dev/docs/components/prose/](https://starwind.dev/docs/components/prose/) · [Markdown](https://starwind.dev/docs/components/prose.md)

# Prose

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Prose } from "@/components/starwind/prose";
---

<Prose>
  <h1>Welcome to Starwind</h1>
  <p>
    Starwind UI is a <strong>beautiful component library</strong> designed for
    the modern web. It provides accessible, customizable components that work
    seamlessly with <a href="#">Astro</a> and Tailwind CSS.
  </p>
  <h2>Getting Started</h2>
  <p>
    Installation is simple. Just run the CLI command and you're ready to go. Here's a quick example: <code
      >npx starwind@latest add prose</code
    >
  </p>
  <h3>Key Features</h3>
  <ul>
    <li>Fully accessible components following WAI-ARIA guidelines</li>
    <li>Customizable via CSS variables and Tailwind classes</li>
    <li>TypeScript support out of the box</li>
  </ul>
  <blockquote>
    <p>Build beautiful interfaces without the complexity.</p>
  </blockquote>
  <p>
    For more information, check out the <mark>documentation</mark> or join our
    community.
  </p>
</Prose>
```
  </div>
  <div slot="react">
```tsx
import { Prose } from "@/components/starwind/prose";

export function Example() {
  return (
    <>
      <Prose>
        <h1>Welcome to Starwind</h1>
        <p>
              Starwind UI is a <strong>beautiful component library</strong> designed for
              the modern web. It provides accessible, customizable components that work
              seamlessly with <a href="#">Astro</a> and Tailwind CSS.
        </p>
        <h2>Getting Started</h2>
        <p>
              Installation is simple. Just run the CLI command and you're ready to go. Here's a quick example: <code
                >npx starwind@latest add prose</code
              >
        </p>
        <h3>Key Features</h3>
        <ul>
          <li>Fully accessible components following WAI-ARIA guidelines</li>
          <li>Customizable via CSS variables and Tailwind classes</li>
          <li>TypeScript support out of the box</li>
        </ul>
        <blockquote>
          <p>Build beautiful interfaces without the complexity.</p>
        </blockquote>
        <p>
              For more information, check out the <mark>documentation</mark> or join our
              community.
        </p>
      </Prose>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add prose
```

## Usage

### General Notes

The Prose component applies beautiful typography styles to markdown and rich text content. It handles headings, paragraphs, lists, blockquotes, code blocks, tables, and more.

Sizing is em-based, so it scales with the inherited font-size. Control overall size via Tailwind text utilities like `text-sm md:text-base`.

### With Rendered Markdown

The Prose component works great with Astro's content collections:

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
---
import { render } from "astro:content";
import { Prose } from "@/components/starwind/prose";

const { Content } = await render(entry);
---

<Prose>
  <Content />
</Prose>
```
</div>
<div slot="react">
```tsx
import Content from "./content.mdx";
import { Prose } from "@/components/starwind/prose";

export function Example() {
  return (
    <Prose>
      <Content />
    </Prose>
  );
}
```
</div>
</FrameworkCodeSwitcher>

### Custom Styling

Override default styles using CSS variables. You can apply them inline, via Tailwind arbitrary properties, or through a custom class:

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Prose } from "@/components/starwind/prose";
---

<Prose class="custom-prose">
  <h1>Welcome to Starwind</h1>
  <p>
    Starwind UI is a <strong>beautiful component library</strong> designed for
    the modern web. It provides accessible, customizable components that work
    seamlessly with <a href="#">Astro</a> and Tailwind CSS.
  </p>
  
</Prose>

/* colors */
    --prose-color: var(--color-muted-foreground);

/* headings */
    --prose-h1-size: 3em;
    --prose-heading-font: var(--font-serif);
    --prose-heading-weight: var(--font-weight-medium);

/* links */
    --prose-link-color: var(--color-primary-accent);
    --prose-link-hover-color: --alpha(var(--color-primary-accent) / 80%);

/* blockquotes */
    --prose-blockquote-border-color: var(--color-primary-accent);

/* inline code */
    --prose-code-color: var(--color-primary-accent);
    --prose-code-bg: --alpha(var(--color-primary-accent) / 10%);

/* media */
    --prose-media-border-width: 1px;
    --prose-media-border-radius: var(--radius-md);

/* highlight */
    --prose-highlight-bg-color: --alpha(var(--color-primary-accent) / 20%);
  }
</style>
```
  </div>
  <div slot="react">
```tsx
import type { CSSProperties } from "react";
import { Prose } from "@/components/starwind/prose";

const customProseStyle = {
  "--prose-line-height": 1.7,
  "--prose-spacing": "1.4em",
  "--prose-heading-spacing": "1.7em",
  "--prose-color": "var(--color-muted-foreground)",
  "--prose-h1-size": "3em",
  "--prose-heading-font": "var(--font-serif)",
  "--prose-heading-weight": "var(--font-weight-medium)",
  "--prose-link-color": "var(--color-primary-accent)",
  "--prose-link-hover-color": "--alpha(var(--color-primary-accent) / 80%)",
  "--prose-blockquote-border-color": "var(--color-primary-accent)",
  "--prose-code-color": "var(--color-primary-accent)",
  "--prose-code-bg": "--alpha(var(--color-primary-accent) / 10%)",
  "--prose-media-border-width": "1px",
  "--prose-media-border-radius": "var(--radius-md)",
  "--prose-highlight-bg-color": "--alpha(var(--color-primary-accent) / 20%)",
} as CSSProperties;

export function Example() {
  return (
    <Prose style={customProseStyle}>
      <h1>Welcome to Starwind</h1>
      <p>
        Starwind UI is a <strong>beautiful component library</strong> designed for the modern web.
        It provides accessible, customizable components that work seamlessly with React and
        Tailwind CSS.
      </p>
      {/* ... more content */}
    </Prose>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Inline Overrides

You can also override specific values using Tailwind's arbitrary property syntax for responsive adjustments:

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<Prose class="[--prose-spacing:1.5em] md:[--prose-spacing:1.25em]">
  
</Prose>
```
</div>
<div slot="react">
```tsx
import { Prose } from "@/components/starwind/prose";

export function Example() {
  return (
    <>
      <Prose className="[--prose-spacing:1.5em] md:[--prose-spacing:1.25em]">
        {/* content */}
      </Prose>
    </>
  );
}
```
</div>
</FrameworkCodeSwitcher>

Or set variables on a parent element:

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<div style="--prose-h1-size: 3em;">
  <Prose>
    
  </Prose>
</div>
```
</div>
<div slot="react">
```tsx
import type { CSSProperties } from "react";
import { Prose } from "@/components/starwind/prose";

const style = { "--prose-h1-size": "3em" } as CSSProperties;

export function Example() {
  return (
    <div style={style}>
      <Prose>{/* content with larger h1 */}</Prose>
    </div>
  );
}
```
</div>
</FrameworkCodeSwitcher>

### Opting Out

Use the `not-sw-prose` class on any element to exclude it from prose styling:

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<Prose>
  <h1>Styled Heading</h1>
  <div class="not-sw-prose">
    
    <h2>Unstyled Heading</h2>
  </div>
</Prose>
```
</div>
<div slot="react">
```tsx
import { Prose } from "@/components/starwind/prose";

export function Example() {
  return (
    <>
      <Prose>
        <h1>Styled Heading</h1>
        <div className="not-sw-prose">
          {/* This content won't have prose styles applied */}
          <h2>Unstyled Heading</h2>
        </div>
      </Prose>
    </>
  );
}
```
</div>
</FrameworkCodeSwitcher>

## API Reference
### Prose
- Inherits div attributes.

## CSS Variables Reference

All CSS variables use the `--prose-` prefix. Override them to customize the appearance.

### Typography & Spacing

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-line-height` | `1.6` | Base line height for text |
| `--prose-spacing` | `1.25em` | Vertical spacing between block elements |
| `--prose-heading-spacing` | `1.5em` | Extra spacing before headings |
| `--prose-code-size` | `0.875em` | Font size for code elements |
| `--prose-list-indent` | `1.625em` | Indentation for lists |

### Colors

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-color` | `foreground/80%` | Base text color |
| `--prose-heading-color` | `foreground` | Heading text color |
| `--prose-list-marker-color` | `muted-foreground` | List bullet/number color |

### Headings

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-heading-font` | `inherit` | Font family for headings |
| `--prose-heading-weight` | `600` | Default heading font weight |
| `--prose-heading-line-height` | `1.25` | Line height for headings |
| `--prose-h1-size` | `2.25em` | H1 font size |
| `--prose-h1-weight` | `heading-weight` | H1 font weight |
| `--prose-h2-size` | `1.5em` | H2 font size |
| `--prose-h2-weight` | `heading-weight` | H2 font weight |
| `--prose-h3-size` | `1.25em` | H3 font size |
| `--prose-h3-weight` | `heading-weight` | H3 font weight |
| `--prose-h4-size` | `1em` | H4 font size |
| `--prose-h4-weight` | `heading-weight` | H4 font weight |

### Links

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-link-color` | `foreground` | Link text color |
| `--prose-link-decoration-color` | `primary-accent` | Link underline color |
| `--prose-link-hover-color` | `primary-accent` | Link hover color |

### Strong/Bold

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-strong-color` | `foreground` | Bold text color |
| `--prose-strong-weight` | `600` | Bold text font weight |

### Blockquotes

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-blockquote-color` | `foreground` | Blockquote text color |
| `--prose-blockquote-border-color` | `border` | Blockquote left border color |
| `--prose-blockquote-border-width` | `4px` | Blockquote left border width |

### Inline Code

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-code-bg` | `muted` | Inline code background |
| `--prose-code-color` | `foreground` | Inline code text color |
| `--prose-code-weight` | `500` | Inline code font weight |
| `--prose-code-radius` | `radius-sm` | Inline code border radius |

### Code Blocks

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-pre-border-color` | `border` | Code block border color |
| `--prose-pre-border-radius` | `radius-md` | Code block border radius |

### Tables

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-table-heading-color` | `foreground` | Table header text color |
| `--prose-table-border-color` | `border` | Table border color |

### Media

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-media-border-width` | `0px` | Border width for images/video |
| `--prose-media-border-color` | `border` | Border color for images/video |
| `--prose-media-border-radius` | `0` | Border radius for images/video |

### Highlight/Mark

| Variable | Default | Description |
|----------|---------|-------------|
| `--prose-highlight-color` | `foreground` | Highlighted text color |
| `--prose-highlight-bg-color` | `warning/30%` | Highlighted text background |

## Changelog

### v1.1.1

- Updated Prose styles to use Starwind semantic color tokens directly.

### v1.1.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v1.0.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.15.0

---

Source: [https://starwind.dev/docs/components/radio-group/](https://starwind.dev/docs/components/radio-group/) · [Markdown](https://starwind.dev/docs/components/radio-group.md)

# Radio Group

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";
import { Label } from "@/components/starwind/label";
---

<RadioGroup name="demo-radio" defaultValue="option-1" legend="Choose an option">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="option-1" aria-label="Option 1" value="option-1" />
    <Label for="option-1">Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="option-2" aria-label="Option 2" value="option-2" />
    <Label for="option-2">Option 2</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="option-3" aria-label="Option 3" value="option-3" />
    <Label for="option-3">Option 3</Label>
  </div>
</RadioGroup>
```
  </div>
  <div slot="react">
```tsx
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";
import { Label } from "@/components/starwind/label";

export function Example() {
  return (
    <>
      <RadioGroup name="demo-radio" defaultValue="option-1" legend="Choose an option">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="option-1" aria-label="Option 1" value="option-1" />
          <Label htmlFor="option-1">Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="option-2" aria-label="Option 2" value="option-2" />
          <Label htmlFor="option-2">Option 2</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="option-3" aria-label="Option 3" value="option-3" />
          <Label htmlFor="option-3">Option 3</Label>
        </div>
      </RadioGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add radio-group
```

## Usage

### variant

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";
import { Label } from "@/components/starwind/label";
---

<RadioGroup name="variant-radio" legend="Default" defaultValue="default-1">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="default-1" aria-label="Default Option 1" value="default-1" variant="default" />
    <Label for="default-1">Default Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="default-2" aria-label="Default Option 2" value="default-2" variant="default" />
    <Label for="default-2">Default Option 2</Label>
  </div>
</RadioGroup>

<RadioGroup name="variant-primary" legend="Primary" defaultValue="primary-1">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="primary-1" aria-label="Primary Option 1" value="primary-1" variant="primary" />
    <Label for="primary-1">Primary Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="primary-2" aria-label="Primary Option 2" value="primary-2" variant="primary" />
    <Label for="primary-2">Primary Option 2</Label>
  </div>
</RadioGroup>

<RadioGroup name="variant-secondary" legend="Secondary" defaultValue="secondary-1">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="secondary-1" aria-label="Secondary Option 1" value="secondary-1" variant="secondary" />
    <Label for="secondary-1">Secondary Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="secondary-2" aria-label="Secondary Option 2" value="secondary-2" variant="secondary" />
    <Label for="secondary-2">Secondary Option 2</Label>
  </div>
</RadioGroup>

<RadioGroup name="variant-info" legend="Info" defaultValue="info-1">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="info-1" aria-label="Info Option 1" value="info-1" variant="info" />
    <Label for="info-1">Info Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="info-2" aria-label="Info Option 2" value="info-2" variant="info" />
    <Label for="info-2">Info Option 2</Label>
  </div>
</RadioGroup>

<RadioGroup name="variant-success" legend="Success" defaultValue="success-1">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="success-1" aria-label="Success Option 1" value="success-1" variant="success" />
    <Label for="success-1">Success Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="success-2" aria-label="Success Option 2" value="success-2" variant="success" />
    <Label for="success-2">Success Option 2</Label>
  </div>
</RadioGroup>

<RadioGroup name="variant-warning" legend="Warning" defaultValue="warning-1">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="warning-1" aria-label="Warning Option 1" value="warning-1" variant="warning" />
    <Label for="warning-1">Warning Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="warning-2" aria-label="Warning Option 2" value="warning-2" variant="warning" />
    <Label for="warning-2">Warning Option 2</Label>
  </div>
</RadioGroup>

<RadioGroup name="variant-error" legend="Error" defaultValue="error-1">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="error-1" aria-label="Error Option 1" value="error-1" variant="error" />
    <Label for="error-1">Error Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="error-2" aria-label="Error Option 2" value="error-2" variant="error" />
    <Label for="error-2">Error Option 2</Label>
  </div>
</RadioGroup>
```
  </div>
  <div slot="react">
```tsx
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";
import { Label } from "@/components/starwind/label";

export function Example() {
  return (
    <>
      <RadioGroup name="variant-radio" legend="Default" defaultValue="default-1">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="default-1" aria-label="Default Option 1" value="default-1" variant="default" />
          <Label htmlFor="default-1">Default Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="default-2" aria-label="Default Option 2" value="default-2" variant="default" />
          <Label htmlFor="default-2">Default Option 2</Label>
        </div>
      </RadioGroup>

<RadioGroup name="variant-primary" legend="Primary" defaultValue="primary-1">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="primary-1" aria-label="Primary Option 1" value="primary-1" variant="primary" />
          <Label htmlFor="primary-1">Primary Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="primary-2" aria-label="Primary Option 2" value="primary-2" variant="primary" />
          <Label htmlFor="primary-2">Primary Option 2</Label>
        </div>
      </RadioGroup>

<RadioGroup name="variant-secondary" legend="Secondary" defaultValue="secondary-1">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="secondary-1" aria-label="Secondary Option 1" value="secondary-1" variant="secondary" />
          <Label htmlFor="secondary-1">Secondary Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="secondary-2" aria-label="Secondary Option 2" value="secondary-2" variant="secondary" />
          <Label htmlFor="secondary-2">Secondary Option 2</Label>
        </div>
      </RadioGroup>

<RadioGroup name="variant-info" legend="Info" defaultValue="info-1">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="info-1" aria-label="Info Option 1" value="info-1" variant="info" />
          <Label htmlFor="info-1">Info Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="info-2" aria-label="Info Option 2" value="info-2" variant="info" />
          <Label htmlFor="info-2">Info Option 2</Label>
        </div>
      </RadioGroup>

<RadioGroup name="variant-success" legend="Success" defaultValue="success-1">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="success-1" aria-label="Success Option 1" value="success-1" variant="success" />
          <Label htmlFor="success-1">Success Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="success-2" aria-label="Success Option 2" value="success-2" variant="success" />
          <Label htmlFor="success-2">Success Option 2</Label>
        </div>
      </RadioGroup>

<RadioGroup name="variant-warning" legend="Warning" defaultValue="warning-1">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="warning-1" aria-label="Warning Option 1" value="warning-1" variant="warning" />
          <Label htmlFor="warning-1">Warning Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="warning-2" aria-label="Warning Option 2" value="warning-2" variant="warning" />
          <Label htmlFor="warning-2">Warning Option 2</Label>
        </div>
      </RadioGroup>

<RadioGroup name="variant-error" legend="Error" defaultValue="error-1">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="error-1" aria-label="Error Option 1" value="error-1" variant="error" />
          <Label htmlFor="error-1">Error Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="error-2" aria-label="Error Option 2" value="error-2" variant="error" />
          <Label htmlFor="error-2">Error Option 2</Label>
        </div>
      </RadioGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Sizes

Set the radio indicator scale once on `RadioGroup`. `RadioGroupItem` no longer accepts `size`.
Labels are separate components outside the Radio Group's styled scope, so size each `Label`
independently when you want its typography to match.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";
import { Label } from "@/components/starwind/label";
---

<RadioGroup size="sm" name="size-sm" legend="Small" defaultValue="sm-1">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="sm-1" aria-label="Small Option 1" value="sm-1" />
    <Label for="sm-1" size="sm">Small Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="sm-2" aria-label="Small Option 2" value="sm-2" />
    <Label for="sm-2" size="sm">Small Option 2</Label>
  </div>
</RadioGroup>

<RadioGroup size="md" name="size-md" legend="Medium" defaultValue="md-1">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="md-1" aria-label="Medium Option 1" value="md-1" />
    <Label for="md-1" size="md">Medium Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="md-2" aria-label="Medium Option 2" value="md-2" />
    <Label for="md-2" size="md">Medium Option 2</Label>
  </div>
</RadioGroup>

<RadioGroup size="lg" name="size-lg" legend="Large" defaultValue="lg-1">
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="lg-1" aria-label="Large Option 1" value="lg-1" />
    <Label for="lg-1" size="lg">Large Option 1</Label>
  </div>
  <div class="flex gap-2 items-center">
    <RadioGroupItem id="lg-2" aria-label="Large Option 2" value="lg-2" />
    <Label for="lg-2" size="lg">Large Option 2</Label>
  </div>
</RadioGroup>
```
  </div>
  <div slot="react">
```tsx
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";
import { Label } from "@/components/starwind/label";

export function Example() {
  return (
    <>
      <RadioGroup size="sm" name="size-sm" legend="Small" defaultValue="sm-1">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="sm-1" aria-label="Small Option 1" value="sm-1" />
          <Label htmlFor="sm-1" size="sm">Small Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="sm-2" aria-label="Small Option 2" value="sm-2" />
          <Label htmlFor="sm-2" size="sm">Small Option 2</Label>
        </div>
      </RadioGroup>

<RadioGroup size="md" name="size-md" legend="Medium" defaultValue="md-1">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="md-1" aria-label="Medium Option 1" value="md-1" />
          <Label htmlFor="md-1" size="md">Medium Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="md-2" aria-label="Medium Option 2" value="md-2" />
          <Label htmlFor="md-2" size="md">Medium Option 2</Label>
        </div>
      </RadioGroup>

<RadioGroup size="lg" name="size-lg" legend="Large" defaultValue="lg-1">
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="lg-1" aria-label="Large Option 1" value="lg-1" />
          <Label htmlFor="lg-1" size="lg">Large Option 1</Label>
        </div>
        <div className="flex gap-2 items-center">
          <RadioGroupItem id="lg-2" aria-label="Large Option 2" value="lg-2" />
          <Label htmlFor="lg-2" size="lg">Large Option 2</Label>
        </div>
      </RadioGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### orientation

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";
import { Label } from "@/components/starwind/label";
---

<h3>Vertical (Default)</h3>
<RadioGroup name="orientation-vertical" orientation="vertical" defaultValue="vertical-1">
  <div class="space-y-2">
    <div class="flex items-center gap-2">
      <RadioGroupItem id="vertical-1" aria-label="Vertical option 1" value="vertical-1" />
      <Label for="vertical-1">Vertical option 1</Label>
    </div>
    <div class="flex items-center gap-2">
      <RadioGroupItem id="vertical-2" aria-label="Vertical option 2" value="vertical-2" />
      <Label for="vertical-2">Vertical option 2</Label>
    </div>
    <div class="flex items-center gap-2">
      <RadioGroupItem id="vertical-3" aria-label="Vertical option 3" value="vertical-3" />
      <Label for="vertical-3">Vertical option 3</Label>
    </div>
  </div>
</RadioGroup>

<h3>Horizontal</h3>
<RadioGroup name="orientation-horizontal" orientation="horizontal" defaultValue="horizontal-1">
  <div class="flex items-center gap-2">
    <RadioGroupItem id="horizontal-1" aria-label="Horizontal option 1" value="horizontal-1" />
    <Label for="horizontal-1">Horizontal option 1</Label>
  </div>
  <div class="flex items-center gap-2">
    <RadioGroupItem id="horizontal-2" aria-label="Horizontal option 2" value="horizontal-2" />
    <Label for="horizontal-2">Horizontal option 2</Label>
  </div>
  <div class="flex items-center gap-2">
    <RadioGroupItem id="horizontal-3" aria-label="Horizontal option 3" value="horizontal-3" />
    <Label for="horizontal-3">Horizontal option 3</Label>
  </div>
</RadioGroup>
```
  </div>
  <div slot="react">
```tsx
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";
import { Label } from "@/components/starwind/label";

export function Example() {
  return (
    <>
      <h3>Vertical (Default)</h3>
      <RadioGroup name="orientation-vertical" orientation="vertical" defaultValue="vertical-1">
        <div className="space-y-2">
          <div className="flex items-center gap-2">
            <RadioGroupItem id="vertical-1" aria-label="Vertical option 1" value="vertical-1" />
            <Label htmlFor="vertical-1">Vertical option 1</Label>
          </div>
          <div className="flex items-center gap-2">
            <RadioGroupItem id="vertical-2" aria-label="Vertical option 2" value="vertical-2" />
            <Label htmlFor="vertical-2">Vertical option 2</Label>
          </div>
          <div className="flex items-center gap-2">
            <RadioGroupItem id="vertical-3" aria-label="Vertical option 3" value="vertical-3" />
            <Label htmlFor="vertical-3">Vertical option 3</Label>
          </div>
        </div>
      </RadioGroup>

<h3>Horizontal</h3>
      <RadioGroup name="orientation-horizontal" orientation="horizontal" defaultValue="horizontal-1">
        <div className="flex items-center gap-2">
          <RadioGroupItem id="horizontal-1" aria-label="Horizontal option 1" value="horizontal-1" />
          <Label htmlFor="horizontal-1">Horizontal option 1</Label>
        </div>
        <div className="flex items-center gap-2">
          <RadioGroupItem id="horizontal-2" aria-label="Horizontal option 2" value="horizontal-2" />
          <Label htmlFor="horizontal-2">Horizontal option 2</Label>
        </div>
        <div className="flex items-center gap-2">
          <RadioGroupItem id="horizontal-3" aria-label="Horizontal option 3" value="horizontal-3" />
          <Label htmlFor="horizontal-3">Horizontal option 3</Label>
        </div>
      </RadioGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Give each Runtime radio an explicit accessible name. The styled radio uses a focusable
`role="radio"` element while its hidden input handles native form participation.

### Event Handling

The RadioGroup component emits a `starwind:value-change` event when a radio option is selected. This can be listened to in order to update your UI based on the `event.detail.value` property.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";
import { Label } from "@/components/starwind/label";
---

<div class="space-y-4">
  <h3 class="text-lg font-medium">Radio Group Event Test</h3>

<RadioGroup id="event-test" name="event-test" legend="Choose an option">
    <div class="flex gap-2">
      <RadioGroupItem id="event-1" aria-label="Option One" value="one" />
      <Label for="event-1">Option One</Label>
    </div>
    <div class="flex gap-2">
      <RadioGroupItem id="event-2" aria-label="Option Two" value="two" />
      <Label for="event-2">Option Two</Label>
    </div>
    <div class="flex gap-2">
      <RadioGroupItem id="event-3" aria-label="Option Three" value="three" />
      <Label for="event-3">Option Three</Label>
    </div>
  </RadioGroup>

<div id="event-output" class="text-muted-foreground text-sm">
    Selected value: <span class="text-foreground font-medium">none</span>
  </div>
</div>

root?.addEventListener("starwind:value-change", (event) => {
    const { value } = (event as CustomEvent<{ value: string }>).detail;
    if (output) output.textContent = value;
  });
</script>
```
  </div>
  <div slot="react">
```tsx
import { useState } from "react";
import { Label } from "@/components/starwind/label";
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";

export function Example() {
  const [value, setValue] = useState<string | null>(null);

return (
    <div className="space-y-4">
      <h3 className="text-lg font-medium">Radio Group Event Test</h3>
      <RadioGroup
        name="event-test"
        legend="Choose an option"
        onValueChange={(nextValue) => setValue(nextValue)}
      >
        {["one", "two", "three"].map((option) => (
          <div key={option} className="flex gap-2">
            <RadioGroupItem id={"event-" + option} aria-label={"Option " + option} value={option} />
            <Label htmlFor={"event-" + option}>Option {option}</Label>
          </div>
        ))}
      </RadioGroup>
      <div className="text-muted-foreground text-sm">
        Selected value: <span className="text-foreground font-medium">{value ?? "none"}</span>
      </div>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Size migration

| Before | After |
| --- | --- |
| `<RadioGroup><RadioGroupItem size="sm" /></RadioGroup>` | `<RadioGroup size="sm"><RadioGroupItem /></RadioGroup>` |

External `Label` components remain independently sizeable.

## API Reference
### RadioGroup
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultValue` | `string` | No | - | Primitive override | Sets the initial value when the component is uncontrolled. |
| `legend` | `string` | No | - | Wrapper prop | Provides accessible text for the grouped choices. |
| `orientation` | `"vertical" \| "horizontal"` | No | `"vertical"` | Styled variant | Selects the horizontal or vertical layout direction. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Wrapper prop | Selects the component's visual size. |
| `value` | `string` | No | - | Primitive override | Controls or identifies the component value. |
- Inherits div attributes. Omits `defaultValue` and `onChange`.

### RadioGroupItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultChecked` | `boolean` | No | - | Primitive override | Sets the initial checked state when the choice is uncontrolled. |
| `variant` | `"default" \| "primary" \| "secondary" \| "info" \| "success" \| "warning" \| "error"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits span attributes. Omits `defaultChecked` and `onChange`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Radio Primitive](/docs/primitives/radio/)
- Primitive: [Radio Group Primitive](/docs/primitives/radio-group/)
- Runtime factory: [`createRadio`](/docs/runtime/#create-radio) from `@starwind-ui/runtime/radio`
- Runtime factory: [`createRadioGroup`](/docs/runtime/#create-radio-group) from `@starwind-ui/runtime/radio-group`

## Changelog

### v3.0.2

- Radio Group items now use the neutral `default` variant when `variant` is omitted.

### v3.0.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v3.0.0

- Moved radio indicator sizing from `RadioGroupItem` to `RadioGroup`, with `md` as the default.
- Migration: `<RadioGroupItem size="sm" />` becomes
`<RadioGroup size="sm"><RadioGroupItem /></RadioGroup>`. Keep `size` on external `Label`
components when desired.

### v2.0.0

- Rebuilt Radio Group on Starwind Runtime for radio ownership, form participation, keyboard navigation, and value details.
- See the [Radio Primitive](/docs/primitives/radio/) and [Radio Group Primitive](/docs/primitives/radio-group/) for the underlying unstyled anatomy and behavior API.

### v1.2.6

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.2.4

- Add `starwind:init` event listener to enable initialization of additional Radio Groups loaded after an initial page load, such as when using server islands

### v1.2.3

- add `aria-invalid` styling

### v1.2.2

- Removed debug logging statements

### v1.2.1

- Add named slot "icon" to `RadioGroupItem` to enable easy icon swapping

### v1.2.0

- style and focus state updates

### v1.1.0

- Add `data-slot` attribute to enable global styling updates

### v1.0.0

- Initial release with starwind v1.7.0

---

Source: [https://starwind.dev/docs/components/scroll-area/](https://starwind.dev/docs/components/scroll-area/) · [Markdown](https://starwind.dev/docs/components/scroll-area.md)

# Scroll Area

ScrollArea,
ScrollBar,
} from "@/components/starwind/scroll-area";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { ScrollArea } from "@/components/starwind/scroll-area";
import { Separator } from "@/components/starwind/separator";

const tags = Array.from({ length: 50 }).map((_, i, a) => `v1.2.0-beta.${a.length - i}`);
---

<ScrollArea class="h-72 w-48 rounded-md border">
  <div class="p-4">
    <h4 class="mb-4 text-sm leading-none font-medium">Tags</h4>
    {
      tags.map((tag) => (
        <div>
          <div class="text-sm">{tag}</div>
          <Separator class="my-2" />
        </div>
      ))
    }
  </div>
</ScrollArea>
```
  </div>
  <div slot="react">
```tsx
import { ScrollArea } from "@/components/starwind/scroll-area";
import { Separator } from "@/components/starwind/separator";

const tags = Array.from({ length: 50 }).map((_, i, a) => `v1.2.0-beta.${a.length - i}`);

export function Example() {
  return (
    <>
      <ScrollArea className="h-72 w-48 rounded-md border">
        <div className="p-4">
          <h4 className="mb-4 text-sm leading-none font-medium">Tags</h4>
              {
                tags.map((tag) => (
            <div key={tag}>
              <div className="text-sm">{tag}</div>
              <Separator className="my-2" />
            </div>
                ))
}
        </div>
      </ScrollArea>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add scroll-area
```

## Usage

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
---
import { ScrollArea, ScrollBar } from "@/components/starwind/scroll-area";
---
```
</div>
<div slot="react">
```tsx
import { ScrollArea, ScrollBar } from "@/components/starwind/scroll-area";
```
</div>
</FrameworkCodeSwitcher>

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<ScrollArea class="h-[200px] w-[350px] rounded-md border p-4">
  Your scrollable content here.
</ScrollArea>
```
</div>
<div slot="react">
```tsx
import { ScrollArea } from "@/components/starwind/scroll-area";

export function Example() {
  return (
    <>
      <ScrollArea className="h-[200px] w-[350px] rounded-md border p-4">
        Your scrollable content here.
      </ScrollArea>
    </>
  );
}
```
</div>
</FrameworkCodeSwitcher>

## Composition

Use the following composition to build a `ScrollArea`:

```text
ScrollArea
└── ScrollBar
```

## Examples

### Horizontal

Use `ScrollBar` with `orientation="horizontal"` for horizontal scrolling.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { ScrollArea, ScrollBar } from "@/components/starwind/scroll-area";
---

<ScrollArea class="w-full max-w-xl rounded-md border" viewportClass="whitespace-nowrap">
  <div class="flex w-max gap-2 p-4">
    <span class="bg-muted text-muted-foreground rounded-md px-3 py-1.5 text-sm">#Astro</span>
    <span class="bg-muted text-muted-foreground rounded-md px-3 py-1.5 text-sm">#Tailwind</span>
    <span class="bg-muted text-muted-foreground rounded-md px-3 py-1.5 text-sm">#TypeScript</span>
  </div>
  <ScrollBar slot="scrollbar" orientation="horizontal" />
</ScrollArea>
```
  </div>
  <div slot="react">
```tsx
        import { ScrollArea, ScrollBar } from "@/components/starwind/scroll-area";

export function Example() {
          return (
            <>
              <ScrollArea
  className="w-full max-w-xl rounded-md border"
  viewportClassName="whitespace-nowrap"
  scrollbar={<ScrollBar orientation="horizontal" />}
>
                <div className="flex w-max gap-2 p-4">
                  <span className="bg-muted text-muted-foreground rounded-md px-3 py-1.5 text-sm">#Astro</span>
                  <span className="bg-muted text-muted-foreground rounded-md px-3 py-1.5 text-sm">#Tailwind</span>
                  <span className="bg-muted text-muted-foreground rounded-md px-3 py-1.5 text-sm">#TypeScript</span>
                </div>
              </ScrollArea>
            </>
          );
        }
```
  </div>
</FrameworkCodeSwitcher>

### RTL

You can enable RTL behavior by placing the component inside a container with `dir="rtl"`.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { ScrollArea } from "@/components/starwind/scroll-area";
import { Separator } from "@/components/starwind/separator";
---

const tags = Array.from({ length: 50 }).map((_, i, a) => `v1.2.0-beta.${a.length - i}`);

<div class="w-full max-w-md" dir="rtl">
  <ScrollArea class="h-72 w-48 rounded-md border">
    <div class="p-4 text-right">
      <h4 class="mb-4 text-sm leading-none font-medium">العلامات</h4>
      {
        tags.map((tag) => (
          <div>
            <div class="text-sm">{tag}</div>
            <Separator class="my-2" />
          </div>
        ))
      }
    </div>
  </ScrollArea>
</div>
```
  </div>
  <div slot="react">
```tsx
import { ScrollArea } from "@/components/starwind/scroll-area";
import { Separator } from "@/components/starwind/separator";

const tags = Array.from({ length: 50 }, (_, index) => `v1.2.0-beta.${50 - index}`);

export function Example() {
  return (
    <div className="w-full max-w-md" dir="rtl">
      <ScrollArea className="h-72 w-48 rounded-md border">
        <div className="p-4 text-right">
          <h4 className="mb-4 text-sm leading-none font-medium">Ø§Ù„Ø¹Ù„Ø§Ù…Ø§Øª</h4>
          {tags.map((tag) => (
            <div key={tag}>
              <div className="text-sm">{tag}</div>
              <Separator className="my-2" />
            </div>
          ))}
        </div>
      </ScrollArea>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### ScrollArea
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `overflowEdgeThreshold` | `number` | No | - | Primitive override | Sets the distance from an edge that counts as overflow. |
| `viewportClass` | `string` | No | - | Wrapper prop | Adds classes to the generated viewport element. |
- Inherits div attributes.

### ScrollAreaViewport
- Inherits div attributes.

### ScrollAreaContent
- Inherits div attributes.

### ScrollBar
- Inherits div attributes.

### ScrollAreaThumb
- Inherits div attributes.

### ScrollAreaCorner
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Scroll Area Primitive](/docs/primitives/scroll-area/)
- Runtime factory: [`createScrollArea`](/docs/runtime/#create-scroll-area) from `@starwind-ui/runtime/scroll-area`

## Changelog

### v2.0.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.0

- Rebuilt Scroll Area on Starwind Runtime with viewport, content, scrollbar, thumb, and corner anatomy.
- See the [Scroll Area Primitive](/docs/primitives/scroll-area/) for the underlying unstyled anatomy and behavior API.

### v1.0.0

- Initial Release with Starwind v2.0.0

---

Source: [https://starwind.dev/docs/components/select/](https://starwind.dev/docs/components/select/) · [Markdown](https://starwind.dev/docs/components/select.md)

# Select

Select,
SelectContent,
SelectGroup,
SelectItem,
SelectLabel,
SelectSeparator,
SelectTrigger,
} from "@/components/starwind/select";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
} from "@/components/starwind/select";
---

<Select name="framework" defaultValue="astro" required>
  <SelectTrigger placeholder="Choose a framework" />
  <SelectContent>
    <SelectItem value="astro">Astro</SelectItem>
    <SelectItem value="react">React</SelectItem>
    <SelectItem value="vue">Vue</SelectItem>
  </SelectContent>
</Select>
```
  </div>
  <div slot="react">
```tsx
import {
      Select,
      SelectContent,
      SelectItem,
      SelectTrigger,
    } from "@/components/starwind/select";

export function Example() {
  return (
    <>
      <Select name="framework" defaultValue="astro" required>
        <SelectTrigger placeholder="Choose a framework" />
        <SelectContent>
          <SelectItem value="astro">Astro</SelectItem>
          <SelectItem value="react">React</SelectItem>
          <SelectItem value="vue">Vue</SelectItem>
        </SelectContent>
      </Select>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add select
```

## Usage

### Sizes

`SelectTrigger` and the portaled `SelectContent` are independent physical scopes. Each accepts
`sm`, `md` (the default), or `lg` and emits its resolved `data-size`. Set both when they should
match; deliberately choose different values when a compact control should open a roomier popup.

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
{(["sm", "md", "lg"] as const).map((size) => (
  <Select defaultValue="astro">
    <SelectTrigger size={size} placeholder={`${size} trigger`} />
    <SelectContent size={size}>
      <SelectItem value="astro">Astro</SelectItem>
      <SelectItem value="react">React</SelectItem>
      <SelectItem value="vue">Vue</SelectItem>
    </SelectContent>
  </Select>
))}

<Select defaultValue="astro">
  <SelectTrigger size="sm" placeholder="Compact trigger" />
  <SelectContent size="lg">
    <SelectItem value="astro">Astro</SelectItem>
    <SelectItem value="react">React</SelectItem>
    <SelectItem value="vue">Vue</SelectItem>
  </SelectContent>
</Select>
```
</div>
<div slot="react">
```tsx
import { Select, SelectContent, SelectItem, SelectTrigger } from "@/components/starwind/select";

export function Example() {
  return (
    <>
      {(["sm", "md", "lg"] as const).map((size) => (
        <Select key={size} defaultValue="astro">
          <SelectTrigger size={size} placeholder={`${size} trigger`} />
          <SelectContent size={size}>
            <SelectItem value="astro">Astro</SelectItem>
            <SelectItem value="react">React</SelectItem>
            <SelectItem value="vue">Vue</SelectItem>
          </SelectContent>
        </Select>
      ))}

<Select defaultValue="astro">
        <SelectTrigger size="sm" placeholder="Compact trigger" />
        <SelectContent size="lg">
          <SelectItem value="astro">Astro</SelectItem>
          <SelectItem value="react">React</SelectItem>
          <SelectItem value="vue">Vue</SelectItem>
        </SelectContent>
      </Select>
    </>
  );
}
```
</div>
</FrameworkCodeSwitcher>

### Form participation

Select serializes its value through a hidden input and follows native form reset behavior.

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<form>
  <Select name="role" required>
    <SelectTrigger placeholder="Choose a role" />
    <SelectContent>
      <SelectItem value="admin">Administrator</SelectItem>
      <SelectItem value="member">Member</SelectItem>
    </SelectContent>
  </Select>
  <button type="submit">Save</button>
</form>
```
</div>
<div slot="react">
```tsx
import { useState } from "react";
import { Select, SelectContent, SelectItem, SelectTrigger } from "@/components/starwind/select";

export function Example() {
  const [submittedRole, setSubmittedRole] = useState<string | null>(null);

return (
      <form
        onSubmit={(event) => {
          event.preventDefault();
          const data = new FormData(event.currentTarget);
          setSubmittedRole(String(data.get("role") ?? ""));
        }}
      >
        <Select name="role" required>
          <SelectTrigger placeholder="Choose a role" />
          <SelectContent>
            <SelectItem value="admin">Administrator</SelectItem>
            <SelectItem value="member">Member</SelectItem>
          </SelectContent>
        </Select>
        <button type="submit">Save</button>
        {submittedRole !== null && (
          <output aria-live="polite">Submitted role: {submittedRole}</output>
        )}
      </form>
  );
}
```
</div>
</FrameworkCodeSwitcher>

### Programmatic value changes

Dispatch `starwind:set-value` on the Select root. Listen for the root-scoped
`starwind:value-change` event when the selected value changes.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
<Select id="role-select" name="role">
  <SelectTrigger placeholder="Choose a role" />
  <SelectContent>
    <SelectItem value="admin">Administrator</SelectItem>
    <SelectItem value="member">Member</SelectItem>
  </SelectContent>
</Select>

<button id="choose-admin" type="button">Choose administrator</button>

button?.addEventListener("click", () => {
    select?.dispatchEvent(
      new CustomEvent("starwind:set-value", {
        detail: { value: "admin" },
      }),
    );
  });

select?.addEventListener("starwind:value-change", (event) => {
    const { value } = (event as CustomEvent<{ value: string | null }>).detail;
    console.log(value);
  });
</script>
```
  </div>
  <div slot="react">
```tsx
import { useState } from "react";
import { Select, SelectContent, SelectItem, SelectTrigger } from "@/components/starwind/select";

export function Example() {
  const [value, setValue] = useState<string | null>(null);

return (
    <>
      <Select
        name="role"
        value={value}
        onValueChange={(nextValue) => {
          setValue(nextValue);
          console.log(nextValue);
        }}
      >
        <SelectTrigger placeholder="Choose a role" />
        <SelectContent>
          <SelectItem value="admin">Administrator</SelectItem>
          <SelectItem value="member">Member</SelectItem>
        </SelectContent>
      </Select>
      <button type="button" onClick={() => setValue("admin")}>
        Choose administrator
      </button>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

For a searchable text input with listbox suggestions, install [Combobox](/docs/components/combobox)
instead of adding the removed search part.

## API Reference
### Select
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultOpen` | `boolean` | No | `false` | Primitive override | Sets the initial open state when the component is uncontrolled. |
| `disabled` | `boolean` | No | `false` | Primitive override | Disables interaction with the component. |
| `required` | `boolean` | No | `false` | Primitive override | Marks the control as required for form validation. |
- Inherits div attributes. Omits `defaultValue` and `onChange`.

### SelectTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Primitive override | Merges the component behavior and props into its child element. |
| `iconClass` | `string` | No | - | Wrapper prop | Adds classes to the component's generated icon. |
| `placeholder` | `string` | No | - | Wrapper prop | Provides fallback text for the value element generated inside the trigger. |
| `showIcon` | `boolean` | No | `true` | Wrapper prop | Shows the component's generated icon. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `valueClass` | `string` | No | - | Wrapper prop | Adds classes to the generated value element. |
- Inherits button attributes.

### SelectValue
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `placeholder` | `string` | No | - | Wrapper prop | Provides fallback text when no value is available. |
- Inherits span attributes.

### SelectContent
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Wrapper prop | Selects the component's visual size. |
- Inherits div attributes.

### SelectItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `disabled` | `boolean` | No | `false` | Styled variant | Disables interaction with the component. |
| `indicatorClass` | `string` | No | - | Wrapper prop | Adds classes to the generated selection indicator. |
| `inset` | `boolean` | No | `false` | Styled variant | Adds leading inset spacing for visual alignment. |
| `showIndicator` | `boolean` | No | `true` | Wrapper prop | Shows the generated selection indicator. |
| `value` | `string` | Yes | - | Primitive override | Controls or identifies the component value. |
- Inherits div attributes. Omits `role`.

### SelectItemText
- Inherits span attributes.

### SelectItemIndicator
- Inherits span attributes.

### SelectGroup
- Inherits div attributes.

### SelectLabel
- Inherits div attributes.

### SelectSeparator
- Inherits div attributes.

### SelectScrollUpButton
- Inherits div attributes.

### SelectScrollDownButton
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Select Primitive](/docs/primitives/select/)
- Runtime factory: [`createSelect`](/docs/runtime/#create-select) from `@starwind-ui/runtime/select`

## Changelog

### v2.0.2

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.1

- `SelectTrigger` and `SelectContent` now expose their independently resolved size as
`data-size`, including the `md` default. No prop migration is required; set both props when the
control and portal should match.

### v2.0.0

- Rebuilt Select on Starwind Runtime for selection, forms, events, and scroll behavior; search is now provided by Combobox.
- See the [Select Primitive](/docs/primitives/select/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/separator/](https://starwind.dev/docs/components/separator/) · [Markdown](https://starwind.dev/docs/components/separator.md)

# Separator

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Separator } from "@/components/starwind/separator";
---

<div>
  <h4 class="text-sm font-medium">Starwind UI</h4>
  <p class="text-sm text-muted-foreground">A beautiful component library for Astro.</p>
</div>
<Separator />
<div class="flex h-5 items-center space-x-4 text-sm">
  <div>Components</div>
  <Separator orientation="vertical" />
  <div>Documentation</div>
  <Separator orientation="vertical" />
  <div>Examples</div>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Separator } from "@/components/starwind/separator";

export function Example() {
  return (
    <>
      <div>
        <h4 className="text-sm font-medium">Starwind UI</h4>
        <p className="text-sm text-muted-foreground">A beautiful component library for Astro.</p>
      </div>
      <Separator />
      <div className="flex h-5 items-center space-x-4 text-sm">
        <div>Components</div>
        <Separator orientation="vertical" />
        <div>Documentation</div>
        <Separator orientation="vertical" />
        <div>Examples</div>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add separator
```

## Usage

### Horizontal (Default)

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Separator } from "@/components/starwind/separator";
---

<div class="space-y-1">
  <h4 class="text-sm font-medium leading-none">Horizontal Separator</h4>
  <p class="text-sm text-muted-foreground">This is the default orientation.</p>
</div>
<Separator />
<div class="space-y-1">
  <h4 class="text-sm font-medium leading-none">Content Below</h4>
  <p class="text-sm text-muted-foreground">The separator divides content vertically.</p>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Separator } from "@/components/starwind/separator";

export function Example() {
  return (
    <>
      <div className="space-y-1">
        <h4 className="text-sm font-medium leading-none">Horizontal Separator</h4>
        <p className="text-sm text-muted-foreground">This is the default orientation.</p>
      </div>
      <Separator />
      <div className="space-y-1">
        <h4 className="text-sm font-medium leading-none">Content Below</h4>
        <p className="text-sm text-muted-foreground">The separator divides content vertically.</p>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Vertical

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Separator } from "@/components/starwind/separator";
---

<div class="flex h-20 items-center space-x-4">
  <div class="text-sm">Left Content</div>
  <Separator orientation="vertical" />
  <div class="text-sm">Middle Content</div>
  <Separator orientation="vertical" />
  <div class="text-sm">Right Content</div>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Separator } from "@/components/starwind/separator";

export function Example() {
  return (
    <>
      <div className="flex h-20 items-center space-x-4">
        <div className="text-sm">Left Content</div>
        <Separator orientation="vertical" />
        <div className="text-sm">Middle Content</div>
        <Separator orientation="vertical" />
        <div className="text-sm">Right Content</div>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Custom Styling

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Separator } from "@/components/starwind/separator";
---

<div>
  <p class="text-sm">Default border color</p>
</div>
<Separator />

<div>
  <p class="text-sm">Custom color and thickness</p>
</div>
<Separator class="bg-primary h-[2px]" />

<div>
  <p class="text-sm">Dashed style</p>
</div>
<Separator class="bg-transparent border-t border-dashed border-border" />
```
  </div>
  <div slot="react">
```tsx
import { Separator } from "@/components/starwind/separator";

export function Example() {
  return (
    <>
      <div>
        <p className="text-sm">Default border color</p>
      </div>
      <Separator />

<div>
        <p className="text-sm">Custom color and thickness</p>
      </div>
      <Separator className="bg-primary h-[2px]" />

<div>
        <p className="text-sm">Dashed style</p>
      </div>
      <Separator className="bg-transparent border-t border-dashed border-border" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Separator
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | No | `"horizontal"` | Styled variant | Selects the horizontal or vertical layout direction. |
- Inherits div attributes. Omits `aria-orientation` and `role`.

## Changelog

### v1.1.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v1.0.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.10.0

---

Source: [https://starwind.dev/docs/components/sheet/](https://starwind.dev/docs/components/sheet/) · [Markdown](https://starwind.dev/docs/components/sheet.md)

# Sheet

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import { Input } from "@/components/starwind/input";
import { Label } from "@/components/starwind/label";
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/starwind/sheet";
---

<Sheet>
  <SheetTrigger asChild>
    <Button>Open Sheet</Button>
  </SheetTrigger>
  <SheetContent>
    <SheetHeader>
      <SheetTitle>Edit Profile</SheetTitle>
      <SheetDescription>
        Make changes to your profile here. Click save when you're done.
      </SheetDescription>
    </SheetHeader>
    <div class="grid gap-4 px-4">
      <div class="grid gap-2">
        <Label for="name">Name</Label>
        <Input id="name" value="Pedro Duarte" />
      </div>
      <div class="grid gap-2">
        <Label for="username">Username</Label>
        <Input id="username" value="@peduarte" />
      </div>
    </div>
    <SheetFooter>
      <SheetClose asChild>
        <Button type="submit">Save changes</Button>
      </SheetClose>
    </SheetFooter>
  </SheetContent>
</Sheet>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import { Input } from "@/components/starwind/input";
import { Label } from "@/components/starwind/label";
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/starwind/sheet";

export function Example() {
  return (
    <>
      <Sheet>
        <SheetTrigger asChild>
          <Button>Open Sheet</Button>
        </SheetTrigger>
        <SheetContent>
          <SheetHeader>
            <SheetTitle>Edit Profile</SheetTitle>
            <SheetDescription>
              Make changes to your profile here. Click save when you're done.
            </SheetDescription>
          </SheetHeader>
          <div className="grid gap-4 px-4">
            <div className="grid gap-2">
              <Label htmlFor="name">Name</Label>
              <Input id="name" defaultValue="Pedro Duarte" />
            </div>
            <div className="grid gap-2">
              <Label htmlFor="username">Username</Label>
              <Input id="username" defaultValue="@peduarte" />
            </div>
          </div>
          <SheetFooter>
            <SheetClose asChild>
              <Button type="submit">Save changes</Button>
            </SheetClose>
          </SheetFooter>
        </SheetContent>
      </Sheet>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add sheet
```

## Usage

### General Notes

Sheets are slide-out panels that can extend from any edge of the screen. They're built on top of the Dialog component and are great for forms and mobile navigation menus.

The essential components are `Sheet`, `SheetTrigger`, and `SheetContent`. The `SheetHeader`, `SheetFooter`, `SheetTitle`, and `SheetDescription` components provide additional structure.

### side

Sheets can slide out from any side of the screen using the `side` prop.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import { Input } from "@/components/starwind/input";
import { Label } from "@/components/starwind/label";
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/starwind/sheet";
---

<Sheet>
  <SheetTrigger asChild>
    <Button variant="outline">Open Top Sheet</Button>
  </SheetTrigger>
  <SheetContent side="top">
    <SheetHeader>
      <SheetTitle>Top Sheet</SheetTitle>
      <SheetDescription>This sheet opens from the top of the screen.</SheetDescription>
    </SheetHeader>
    <div class="grid gap-4 px-4">
      <div class="grid gap-3">
        <Label for="top-sheet-name">Name</Label>
        <Input id="top-sheet-name" value="Pedro Duarte" />
      </div>
      <div class="grid gap-3">
        <Label for="top-sheet-username">Username</Label>
        <Input id="top-sheet-username" value="@peduarte" />
      </div>
    </div>
    <SheetFooter>
      <Button variant="default">Save changes</Button>
      <SheetClose asChild>
        <Button variant="outline">Close</Button>
      </SheetClose>
    </SheetFooter>
  </SheetContent>
</Sheet>

<SheetContent side="right">...</SheetContent>
<SheetContent side="bottom">...</SheetContent>
<SheetContent side="left">...</SheetContent>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import { Input } from "@/components/starwind/input";
import { Label } from "@/components/starwind/label";
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/starwind/sheet";

export function Example() {
  return (
    <>
      {/* Top Sheet */}
      <Sheet>
        <SheetTrigger asChild>
          <Button variant="outline">Open Top Sheet</Button>
        </SheetTrigger>
        <SheetContent side="top">
          <SheetHeader>
            <SheetTitle>Top Sheet</SheetTitle>
            <SheetDescription>This sheet opens from the top of the screen.</SheetDescription>
          </SheetHeader>
          <div className="grid gap-4 px-4">
            <div className="grid gap-3">
              <Label htmlFor="top-sheet-name">Name</Label>
              <Input id="top-sheet-name" value="Pedro Duarte" />
            </div>
            <div className="grid gap-3">
              <Label htmlFor="top-sheet-username">Username</Label>
              <Input id="top-sheet-username" value="@peduarte" />
            </div>
          </div>
          <SheetFooter>
            <Button variant="default">Save changes</Button>
            <SheetClose asChild>
              <Button variant="outline">Close</Button>
            </SheetClose>
          </SheetFooter>
        </SheetContent>
      </Sheet>

{/* Other sides: right, bottom, left */}
      <SheetContent side="right">...</SheetContent>
      <SheetContent side="bottom">...</SheetContent>
      <SheetContent side="left">...</SheetContent>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Sheet
- Inherits div attributes.

### SheetTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Wrapper prop | Merges the component behavior and props into its child element. |
- Inherits button attributes.

### SheetContent
- Inherits dialog attributes.

### SheetHeader
- Inherits div attributes.

### SheetFooter
- Inherits div attributes.

### SheetTitle
- Inherits h2 attributes.

### SheetDescription
- Inherits p attributes.

### SheetClose
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Wrapper prop | Merges the component behavior and props into its child element. |
- Inherits button attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Drawer Primitive](/docs/primitives/drawer/)
- Runtime factory: [`createDrawer`](/docs/runtime/#create-drawer) from `@starwind-ui/runtime/drawer`

## Changelog

### v2.0.2

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.0

- Rebuilt Sheet on Starwind Runtime while preserving its styled API over the shared Drawer behavior.
- See the [Drawer Primitive](/docs/primitives/drawer/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/sidebar/](https://starwind.dev/docs/components/sidebar/) · [Markdown](https://starwind.dev/docs/components/sidebar.md)

# Sidebar

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import BellIcon from "@tabler/icons/outline/bell.svg";
import BookOpenIcon from "@tabler/icons/outline/book.svg";
import ChartPieIcon from "@tabler/icons/outline/chart-pie.svg";
import ChevronRightIcon from "@tabler/icons/outline/chevron-right.svg";
import ChevronUpIcon from "@tabler/icons/outline/chevron-up.svg";
import CodeIcon from "@tabler/icons/outline/code.svg";
import CreditCardIcon from "@tabler/icons/outline/credit-card.svg";
import FrameIcon from "@tabler/icons/outline/frame.svg";
import LogoutIcon from "@tabler/icons/outline/logout.svg";
import MapIcon from "@tabler/icons/outline/map.svg";
import BotIcon from "@tabler/icons/outline/robot.svg";
import BadgeCheckIcon from "@tabler/icons/outline/rosette-discount-check.svg";
import Settings2Icon from "@tabler/icons/outline/settings-2.svg";
import SparklesIcon from "@tabler/icons/outline/sparkles.svg";
import TerminalIcon from "@tabler/icons/outline/terminal-2.svg";

import { Avatar, AvatarFallback, AvatarImage } from "@/components/starwind/avatar";
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/starwind/collapsible";
import {
  Dropdown,
  DropdownContent,
  DropdownItem,
  DropdownLabel,
  DropdownSeparator,
  DropdownTrigger,
} from "@/components/starwind/dropdown";
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSub,
  SidebarMenuSubButton,
  SidebarMenuSubItem,
  SidebarProvider,
  SidebarRail,
  SidebarSeparator,
  SidebarTrigger,
} from "@/components/starwind/sidebar";

const navMain = [
  {
    title: "Playground",
    url: "#",
    icon: TerminalIcon,
    isActive: true,
    items: [
      { title: "History", url: "#" },
      { title: "Starred", url: "#" },
      { title: "Settings", url: "#" },
    ],
  },
  {
    title: "Models",
    url: "#",
    icon: BotIcon,
    items: [
      { title: "Genesis", url: "#" },
      { title: "Explorer", url: "#" },
      { title: "Quantum", url: "#" },
    ],
  },
  {
    title: "Documentation",
    url: "#",
    icon: BookOpenIcon,
    items: [
      { title: "Introduction", url: "#" },
      { title: "Get Started", url: "#" },
      { title: "Tutorials", url: "#" },
      { title: "Changelog", url: "#" },
    ],
  },
  {
    title: "Settings",
    url: "#",
    icon: Settings2Icon,
    items: [
      { title: "General", url: "#" },
      { title: "Team", url: "#" },
      { title: "Billing", url: "#" },
      { title: "Limits", url: "#" },
    ],
  },
];

const projects = [
  { name: "Design Engineering", url: "#", icon: FrameIcon },
  { name: "Sales & Marketing", url: "#", icon: ChartPieIcon },
  { name: "Travel", url: "#", icon: MapIcon },
];
---

<SidebarProvider>
  <Sidebar collapsible="icon">
    <SidebarHeader>
      <SidebarMenu>
        <SidebarMenuItem>
          <SidebarMenuButton size="lg">
            <div
              class="bg-sidebar-primary text-sidebar-primary-foreground flex aspect-square size-10 items-center justify-center rounded-lg"
            >
              <CodeIcon class="size-5" />
            </div>
            <div class="grid flex-1 text-left text-sm leading-tight">
              <span class="truncate font-semibold">Starwind UI</span>
              <span class="text-sidebar-foreground/70 truncate text-xs">Enterprise</span>
            </div>
          </SidebarMenuButton>
        </SidebarMenuItem>
      </SidebarMenu>
    </SidebarHeader>

<SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel>Platform</SidebarGroupLabel>
        <SidebarGroupContent>
          <SidebarMenu>
            {
              navMain.map((item) => (
                <Collapsible defaultOpen={item.isActive} class="group/collapsible">
                  <SidebarMenuItem>
                    <CollapsibleTrigger asChild>
                      <SidebarMenuButton tooltip={item.title}>
                        <item.icon />
                        <span>{item.title}</span>
                        <ChevronRightIcon class="ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
                      </SidebarMenuButton>
                    </CollapsibleTrigger>
                    {item.items && (
                      <CollapsibleContent>
                        <SidebarMenuSub>
                          {item.items.map((subItem) => (
                            <SidebarMenuSubItem>
                              <SidebarMenuSubButton href={subItem.url}>
                                <span>{subItem.title}</span>
                              </SidebarMenuSubButton>
                            </SidebarMenuSubItem>
                          ))}
                        </SidebarMenuSub>
                      </CollapsibleContent>
                    )}
                  </SidebarMenuItem>
                </Collapsible>
              ))
            }
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>

<SidebarGroup class="group-data-[collapsible=icon]:hidden">
        <SidebarGroupLabel>Projects</SidebarGroupLabel>
        <SidebarGroupContent>
          <SidebarMenu>
            {
              projects.map((project) => (
                <SidebarMenuItem>
                  <SidebarMenuButton href={project.url} tooltip={project.name}>
                    <project.icon />
                    <span>{project.name}</span>
                  </SidebarMenuButton>
                </SidebarMenuItem>
              ))
            }
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>
    </SidebarContent>

<SidebarFooter>
      <SidebarMenu>
        <SidebarMenuItem>
          <Dropdown>
            <DropdownTrigger asChild>
              <SidebarMenuButton size="lg">
                <Avatar class="size-10 shrink-0 rounded-lg">
                  <AvatarImage src="https://github.com/boston343.png" alt="boston343" />
                  <AvatarFallback class="rounded-lg">B3</AvatarFallback>
                </Avatar>
                <div class="grid flex-1 text-left text-sm leading-tight">
                  <span class="truncate font-semibold">Boston343</span>
                  <span class="text-sidebar-foreground/70 truncate text-xs">@boston343</span>
                </div>
                <ChevronUpIcon class="ml-auto size-4" />
              </SidebarMenuButton>
            </DropdownTrigger>
            <DropdownContent class="min-w-48" side="right">
              <DropdownLabel class="p-0 font-normal">
                <div class="flex items-center gap-2 px-1 py-1.5 text-left text-sm">
                  <Avatar class="size-8 rounded-lg">
                    <AvatarImage src="https://github.com/boston343.png" alt="boston343" />
                    <AvatarFallback class="rounded-lg">B3</AvatarFallback>
                  </Avatar>
                  <div class="grid flex-1 text-left text-sm leading-tight">
                    <span class="truncate font-semibold">boston343</span>
                    <span class="text-muted-foreground truncate text-xs">@boston343</span>
                  </div>
                </div>
              </DropdownLabel>
              <DropdownSeparator />
              <DropdownItem>
                <SparklesIcon class="mr-2 size-4" />
                Upgrade to Pro
              </DropdownItem>
              <DropdownSeparator />
              <DropdownItem>
                <BadgeCheckIcon class="mr-2 size-4" />
                Account
              </DropdownItem>
              <DropdownItem>
                <CreditCardIcon class="mr-2 size-4" />
                Billing
              </DropdownItem>
              <DropdownItem>
                <BellIcon class="mr-2 size-4" />
                Notifications
              </DropdownItem>
              <DropdownSeparator />
              <DropdownItem>
                <LogoutIcon class="mr-2 size-4" />
                Log out
              </DropdownItem>
            </DropdownContent>
          </Dropdown>
        </SidebarMenuItem>
      </SidebarMenu>
    </SidebarFooter>

<main class="bg-background flex flex-1 flex-col">
    <header class="flex h-12 shrink-0 items-center gap-2 border-b px-4">
      <SidebarTrigger />
      <span class="text-muted-foreground text-sm">Main Content</span>
    </header>
    <div class="flex-1 p-6">
      <p class="text-muted-foreground text-sm">
        Use <kbd class="bg-muted rounded px-1.5 py-0.5 text-xs font-medium">Ctrl+B</kbd> to toggle
        the sidebar <br /> after clicking in this window.
      </p>
    </div>
  </main>
</SidebarProvider>
```
  </div>
  <div slot="react">
```tsx
import {
  IconBell as BellIcon,
  IconBook as BookOpenIcon,
  IconChartPie as ChartPieIcon,
  IconChevronRight as ChevronRightIcon,
  IconChevronUp as ChevronUpIcon,
  IconCode as CodeIcon,
  IconCreditCard as CreditCardIcon,
  IconFrame as FrameIcon,
  IconLogout as LogoutIcon,
  IconMap as MapIcon,
  IconRobot as BotIcon,
  IconRosetteDiscountCheck as BadgeCheckIcon,
  IconSettings2 as Settings2Icon,
  IconSparkles as SparklesIcon,
  IconTerminal2 as TerminalIcon,
} from "@tabler/icons-react";

const navMain = [
  {
    title: "Playground",
    url: "#",
    Icon: TerminalIcon,
    isActive: true,
    items: [
      { title: "History", url: "#" },
      { title: "Starred", url: "#" },
      { title: "Settings", url: "#" },
    ],
  },
  {
    title: "Models",
    url: "#",
    Icon: BotIcon,
    items: [
      { title: "Genesis", url: "#" },
      { title: "Explorer", url: "#" },
      { title: "Quantum", url: "#" },
    ],
  },
  {
    title: "Documentation",
    url: "#",
    Icon: BookOpenIcon,
    items: [
      { title: "Introduction", url: "#" },
      { title: "Get Started", url: "#" },
      { title: "Tutorials", url: "#" },
      { title: "Changelog", url: "#" },
    ],
  },
  {
    title: "Settings",
    url: "#",
    Icon: Settings2Icon,
    items: [
      { title: "General", url: "#" },
      { title: "Team", url: "#" },
      { title: "Billing", url: "#" },
      { title: "Limits", url: "#" },
    ],
  },
];

const projects = [
  { name: "Design Engineering", url: "#", Icon: FrameIcon },
  { name: "Sales & Marketing", url: "#", Icon: ChartPieIcon },
  { name: "Travel", url: "#", Icon: MapIcon },
];

export function Example() {
  return (
    <>
      <SidebarProvider>
        <Sidebar collapsible="icon">
          <SidebarHeader>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton size="lg">
                      <div
                        className="bg-sidebar-primary text-sidebar-primary-foreground flex aspect-square size-10 items-center justify-center rounded-lg"
                      >
                    <CodeIcon className="size-5" />
                  </div>
                  <div className="grid flex-1 text-left text-sm leading-tight">
                    <span className="truncate font-semibold">Starwind UI</span>
                    <span className="text-sidebar-foreground/70 truncate text-xs">Enterprise</span>
                  </div>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarHeader>

<SidebarContent>
            <SidebarGroup>
              <SidebarGroupLabel>Platform</SidebarGroupLabel>
              <SidebarGroupContent>
                <SidebarMenu>
  {
                        navMain.map((item) => (
                    <Collapsible
                      key={`${item.url}-${item.title}`}
                      defaultOpen={item.isActive}
                      className="group/collapsible"
                    >
                      <SidebarMenuItem>
                        <CollapsibleTrigger asChild>
                          <SidebarMenuButton tooltip={item.title}>
                            <item.Icon />
                            <span>{item.title}</span>
                            <ChevronRightIcon className="ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
                          </SidebarMenuButton>
                        </CollapsibleTrigger>
                        {item.items && (
                          <CollapsibleContent>
                            <SidebarMenuSub>
                              {item.items.map((subItem) => (
                                <SidebarMenuSubItem key={`${subItem.url}-${subItem.title}`}>
                                  <SidebarMenuSubButton href={subItem.url}>
                                    <span>{subItem.title}</span>
                                  </SidebarMenuSubButton>
                                </SidebarMenuSubItem>
                              ))}
                            </SidebarMenuSub>
                          </CollapsibleContent>
                        )}
                      </SidebarMenuItem>
                    </Collapsible>
                        ))
}
                </SidebarMenu>
              </SidebarGroupContent>
            </SidebarGroup>

<SidebarGroup className="group-data-[collapsible=icon]:hidden">
              <SidebarGroupLabel>Projects</SidebarGroupLabel>
              <SidebarGroupContent>
                <SidebarMenu>
  {
                        projects.map((project) => (
                    <SidebarMenuItem key={`${project.url}-${project.name}`}>
                      <SidebarMenuButton href={project.url} tooltip={project.name}>
                        <project.Icon />
                        <span>{project.name}</span>
                      </SidebarMenuButton>
                    </SidebarMenuItem>
                        ))
}
                </SidebarMenu>
              </SidebarGroupContent>
            </SidebarGroup>
          </SidebarContent>

<SidebarFooter>
            <SidebarMenu>
              <SidebarMenuItem>
                <Dropdown>
                  <DropdownTrigger asChild>
                    <SidebarMenuButton size="lg">
                      <Avatar className="size-10 shrink-0 rounded-lg">
                        <AvatarImage src="https://github.com/boston343.png" alt="boston343" />
                        <AvatarFallback className="rounded-lg">B3</AvatarFallback>
                      </Avatar>
                      <div className="grid flex-1 text-left text-sm leading-tight">
                        <span className="truncate font-semibold">Boston343</span>
                        <span className="text-sidebar-foreground/70 truncate text-xs">@boston343</span>
                      </div>
                      <ChevronUpIcon className="ml-auto size-4" />
                    </SidebarMenuButton>
                  </DropdownTrigger>
                  <DropdownContent className="min-w-48" side="right">
                    <DropdownLabel className="p-0 font-normal">
                      <div className="flex items-center gap-2 px-1 py-1.5 text-left text-sm">
                        <Avatar className="size-8 rounded-lg">
                          <AvatarImage src="https://github.com/boston343.png" alt="boston343" />
                          <AvatarFallback className="rounded-lg">B3</AvatarFallback>
                        </Avatar>
                        <div className="grid flex-1 text-left text-sm leading-tight">
                          <span className="truncate font-semibold">boston343</span>
                          <span className="text-muted-foreground truncate text-xs">@boston343</span>
                        </div>
                      </div>
                    </DropdownLabel>
                    <DropdownSeparator />
                    <DropdownItem>
                      <SparklesIcon className="mr-2 size-4" />
                      Upgrade to Pro
                    </DropdownItem>
                    <DropdownSeparator />
                    <DropdownItem>
                      <BadgeCheckIcon className="mr-2 size-4" />
                      Account
                    </DropdownItem>
                    <DropdownItem>
                      <CreditCardIcon className="mr-2 size-4" />
                      Billing
                    </DropdownItem>
                    <DropdownItem>
                      <BellIcon className="mr-2 size-4" />
                      Notifications
                    </DropdownItem>
                    <DropdownSeparator />
                    <DropdownItem>
                      <LogoutIcon className="mr-2 size-4" />
                      Log out
                    </DropdownItem>
                  </DropdownContent>
                </Dropdown>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarFooter>

<main className="bg-background flex flex-1 flex-col">
          <header className="flex h-12 shrink-0 items-center gap-2 border-b px-4">
            <SidebarTrigger />
            <span className="text-muted-foreground text-sm">Main Content</span>
          </header>
          <div className="flex-1 p-6">
            <p className="text-muted-foreground text-sm">
                  Use <kbd className="bg-muted rounded px-1.5 py-0.5 text-xs font-medium">Ctrl+B</kbd> to toggle
                  the sidebar <br /> after clicking in this window.
            </p>
              </div>
        </main>
      </SidebarProvider>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

Sidebars are one of the most complex components to build. They are central to any application and often contain a lot of moving parts.

The Starwind Sidebar is composable, themeable, and customizable.

> **Info:** The Starwind Sidebar is extremely similar to the shadcn/ui sidebar component.

## Installation

```bash
npx starwind@latest add sidebar
```

Add the following colors to your global CSS file (usually `src/styles/starwind.css`) if they do not already exist:

> **Info:** They may not exist if you are adding the sidebar to an existing project. For new projects the `starwind init` command automatically adds this setup.

```scss  title="src/styles/starwind.css"
@theme inline {
  /* other variables... */

--color-sidebar: var(--sidebar-background);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);
  --color-sidebar-outline: var(--sidebar-outline);
}

:root {
  /* other variables... */

/* sidebar variables */
  --sidebar-background: var(--color-neutral-50);
  --sidebar-foreground: var(--color-neutral-950);
  --sidebar-primary: var(--color-blue-700);
  --sidebar-primary-foreground: var(--color-neutral-50);
  --sidebar-accent: var(--color-neutral-100);
  --sidebar-accent-foreground: var(--color-neutral-900);
  --sidebar-border: var(--color-neutral-200);
  --sidebar-outline: var(--color-neutral-400);
}

.dark {
  /* other variables... */

/* sidebars variables */
  --sidebar-background: var(--color-neutral-900);
  --sidebar-foreground: var(--color-neutral-50);
  --sidebar-primary: var(--color-blue-700);
  --sidebar-primary-foreground: var(--color-neutral-50);
  --sidebar-accent: var(--color-neutral-800);
  --sidebar-accent-foreground: var(--color-neutral-100);
  --sidebar-border: var(--color-neutral-800);
  --sidebar-outline: var(--color-neutral-600);
}
```

## Structure

A `Sidebar` component is composed of the following parts:

- **`SidebarProvider`** - Handles collapsible state and keyboard shortcuts
- **`Sidebar`** - The sidebar container
- **`SidebarHeader`** and **`SidebarFooter`** - Sticky at the top and bottom of the sidebar
- **`SidebarContent`** - Scrollable content area
- **`SidebarGroup`** - Section within the `SidebarContent`
- **`SidebarTrigger`** - Button to toggle the sidebar

## Usage

### Basic Layout

Wrap your application with `SidebarProvider` and place `Sidebar` alongside your main content:

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
---
import {
  Sidebar,
  SidebarContent,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/starwind/sidebar";
import { AppSidebar } from "@/components/app-sidebar";
---

<SidebarProvider>
  <AppSidebar />
  <main>
    <SidebarTrigger />
    <slot />
  </main>
</SidebarProvider>
```
</div>
<div slot="react">
```tsx
import type { ReactNode } from "react";
import {
  Sidebar,
  SidebarContent,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/starwind/sidebar";
import { AppSidebar } from "@/components/app-sidebar";

export function Example({ children }: { children: ReactNode }) {
  return (
    <>
      <SidebarProvider>
        <AppSidebar />
        <main>
          <SidebarTrigger />
          {children}
        </main>
      </SidebarProvider>
    </>
  );
}
```
</div>
</FrameworkCodeSwitcher>

### Creating a Sidebar Component

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
---
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarHeader,
} from "@/components/starwind/sidebar";
---

<Sidebar>
  <SidebarHeader />
  <SidebarContent>
    <SidebarGroup />
    <SidebarGroup />
  </SidebarContent>
  <SidebarFooter />
</Sidebar>
```
</div>
<div slot="react">
```tsx
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarHeader,
} from "@/components/starwind/sidebar";

export function Example() {
  return (
    <>
      <Sidebar>
        <SidebarHeader />
        <SidebarContent>
          <SidebarGroup />
          <SidebarGroup />
        </SidebarContent>
        <SidebarFooter />
      </Sidebar>
    </>
  );
}
```
</div>
</FrameworkCodeSwitcher>

### With Menu Items

Use `SidebarMenu`, `SidebarMenuItem`, and `SidebarMenuButton` to create navigation menus.
`SidebarMenuButton` supports `sm`, `md`, and `lg` sizes and defaults to `md`:

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import CalendarIcon from "@tabler/icons/outline/calendar.svg";
import CodeIcon from "@tabler/icons/outline/code.svg";
import HomeIcon from "@tabler/icons/outline/home.svg";
import InboxIcon from "@tabler/icons/outline/inbox.svg";
import SearchIcon from "@tabler/icons/outline/search.svg";
import SettingsIcon from "@tabler/icons/outline/settings.svg";

import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/starwind/sidebar";

const items = [
  { title: "Home", url: "#", icon: HomeIcon },
  { title: "Inbox", url: "#", icon: InboxIcon },
  { title: "Calendar", url: "#", icon: CalendarIcon },
  { title: "Search", url: "#", icon: SearchIcon },
  { title: "Settings", url: "#", icon: SettingsIcon },
];
---

<SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel>Application</SidebarGroupLabel>
        <SidebarGroupContent>
          <SidebarMenu>
            {
              items.map((item) => (
                <SidebarMenuItem>
                  <SidebarMenuButton href={item.url}>
                    <item.icon />
                    <span>{item.title}</span>
                  </SidebarMenuButton>
                </SidebarMenuItem>
              ))
            }
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>
    </SidebarContent>
  </Sidebar>

<main class="bg-background flex flex-1 flex-col">
    <header class="flex h-12 shrink-0 items-center gap-2 border-b px-4">
      <SidebarTrigger />
      <span class="text-muted-foreground text-sm">Main Content</span>
    </header>
    <div class="flex-1 p-6">
      <p class="text-muted-foreground text-sm">
        Use <kbd class="bg-muted rounded px-1.5 py-0.5 text-xs font-medium">Ctrl+B</kbd> to toggle
        the sidebar <br /> after clicking in this window.
      </p>
    </div>
  </main>
</SidebarProvider>
```
  </div>
  <div slot="react">
```tsx
import { IconCalendar as CalendarIcon } from "@tabler/icons-react";
import { IconCode as CodeIcon } from "@tabler/icons-react";
import { IconHome as HomeIcon } from "@tabler/icons-react";
import { IconInbox as InboxIcon } from "@tabler/icons-react";
import { IconSearch as SearchIcon } from "@tabler/icons-react";
import { IconSettings as SettingsIcon } from "@tabler/icons-react";

const items = [
  { title: "Home", url: "#", Icon: HomeIcon },
  { title: "Inbox", url: "#", Icon: InboxIcon },
  { title: "Calendar", url: "#", Icon: CalendarIcon },
  { title: "Search", url: "#", Icon: SearchIcon },
  { title: "Settings", url: "#", Icon: SettingsIcon },
];

export function Example() {
  return (
    <>
      <SidebarProvider>
        <Sidebar collapsible="icon">
          <SidebarHeader>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton size="lg">
                  <div
                    className="bg-sidebar-primary text-sidebar-primary-foreground flex aspect-square size-10 items-center justify-center rounded-lg"
                  >
                    <CodeIcon className="size-5" />
                  </div>
                  <div className="grid flex-1 text-left text-sm leading-tight">
                    <span className="truncate font-semibold">Starwind UI</span>
                    <span className="text-sidebar-foreground/70 truncate text-xs">Enterprise</span>
                  </div>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarHeader>

<SidebarContent>
            <SidebarGroup>
              <SidebarGroupLabel>Application</SidebarGroupLabel>
              <SidebarGroupContent>
                <SidebarMenu>
                  {
                    items.map((item) => (
                      <SidebarMenuItem key={`${item.url}-${item.title}`}>
                        <SidebarMenuButton href={item.url}>
                          <item.Icon />
                          <span>{item.title}</span>
                        </SidebarMenuButton>
                      </SidebarMenuItem>
                    ))
                  }
                </SidebarMenu>
              </SidebarGroupContent>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>

<main className="bg-background flex flex-1 flex-col">
          <header className="flex h-12 shrink-0 items-center gap-2 border-b px-4">
            <SidebarTrigger />
            <span className="text-muted-foreground text-sm">Main Content</span>
          </header>
          <div className="flex-1 p-6">
            <p className="text-muted-foreground text-sm">
              Use <kbd className="bg-muted rounded px-1.5 py-0.5 text-xs font-medium">Ctrl+B</kbd> to toggle
              the sidebar <br /> after clicking in this window.
            </p>
          </div>
        </main>
      </SidebarProvider>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### With Inset Variant

When using the `inset` variant, wrap your main content in `SidebarInset`:

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
---
import {
  Sidebar,
  SidebarInset,
  SidebarProvider,
} from "@/components/starwind/sidebar";
---

<SidebarProvider>
  <Sidebar variant="inset">
    {/* Sidebar content */}
  </Sidebar>
  <SidebarInset>
    <main>{/* Main content */}</main>
  </SidebarInset>
</SidebarProvider>
```
</div>
<div slot="react">
```tsx
import {
  Sidebar,
  SidebarInset,
  SidebarProvider,
} from "@/components/starwind/sidebar";

export function Example() {
  return (
    <>
      <SidebarProvider>
        <Sidebar variant="inset">
          {/* Sidebar content */}
        </Sidebar>
        <SidebarInset>
          <main>{/* Main content */}</main>
        </SidebarInset>
      </SidebarProvider>
    </>
  );
}
```
</div>
</FrameworkCodeSwitcher>

## API Reference
### SidebarProvider
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `persistenceKey` | `string` | No | - | Primitive override | Sets the storage key used for persisted state. |
| `persistenceStorage` | `"localStorage" \| "cookie" \| false` | No | - | Primitive override | Selects where persisted state is stored. |
- Inherits div attributes.

### Sidebar
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `collapsible` | `"offcanvas" \| "icon" \| "none"` | No | `"offcanvas"` | Primitive override | Selects how the component can collapse. |
- Inherits div attributes.

### SidebarTrigger
- Inherits Button props.

### SidebarRail
- Inherits button attributes.

### SidebarInset
- Inherits main attributes.

### SidebarContent
- Inherits div attributes.

### SidebarHeader
- Inherits div attributes.

### SidebarFooter
- Inherits div attributes.

### SidebarGroup
- Inherits div attributes.

### SidebarGroupLabel
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Wrapper prop | Preserves the Sidebar Group Label recipe on its existing wrapper while rendering the supplied child inside it. |
- Inherits div attributes.

### SidebarGroupAction
- Inherits Button props.

### SidebarGroupContent
- Inherits div attributes.

### SidebarInput
- Inherits Input props.

### SidebarSeparator
- Inherits Separator props.

### SidebarMenu
- Inherits ul attributes.

### SidebarMenuItem
- Inherits li attributes.

### SidebarMenuButton
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Wrapper prop | Merges the component behavior and props into its child element. |
| `isActive` | `boolean` | No | `false` | Wrapper prop | Applies the active visual state. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `tooltip` | `string` | No | - | Wrapper prop | Provides collapsed-sidebar tooltip text for this menu button. |
| `variant` | `"default" \| "outline"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits a attributes. Omits `type`.
- Inherits button attributes.

### SidebarMenuAction
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `showOnHover` | `boolean` | No | `false` | Wrapper prop | Reveals the action when its containing item is hovered. |
- Inherits Button props.

### SidebarMenuBadge
- Inherits div attributes.

### SidebarMenuSkeleton
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `showIcon` | `boolean` | No | `false` | Wrapper prop | Shows the component's generated icon. |
| `width` | `string` | No | - | Wrapper prop | Sets the component width. |
- Inherits div attributes.

### SidebarMenuSub
- Inherits ul attributes.

### SidebarMenuSubItem
- Inherits li attributes.

### SidebarMenuSubButton
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `isActive` | `boolean` | No | `false` | Wrapper prop | Applies the active visual state. |
| `size` | `"sm" \| "md"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits a attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Sidebar Primitive](/docs/primitives/sidebar/)
- Runtime factory: [`createSidebarController`](/docs/runtime/#create-sidebar-controller) from `@starwind-ui/runtime/sidebar`

## Changelog

### v2.1.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.1.0

- Renamed the standard `SidebarMenuButton` size from `default` to `md`. Omitting `size` keeps the same medium styling.

### v2.0.0

- Rebuilt Sidebar on Starwind Runtime for provider, collapsed, mobile, and control state.
- See the [Sidebar Primitive](/docs/primitives/sidebar/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/skeleton/](https://starwind.dev/docs/components/skeleton/) · [Markdown](https://starwind.dev/docs/components/skeleton.md)

# Skeleton

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Skeleton } from "@/components/starwind/skeleton";
---

<div class="flex items-center space-x-4">
  <Skeleton class="h-12 w-12 rounded-full" />
  <div class="space-y-2">
    <Skeleton class="h-4 w-[250px]" />
    <Skeleton class="h-4 w-[200px]" />
  </div>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Skeleton } from "@/components/starwind/skeleton";

export function Example() {
  return (
    <>
      <div className="flex items-center space-x-4">
        <Skeleton className="h-12 w-12 rounded-full" />
        <div className="space-y-2">
          <Skeleton className="h-4 w-[250px]" />
          <Skeleton className="h-4 w-[200px]" />
        </div>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add skeleton
```

## Usage

### Card Skeleton

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Skeleton } from "@/components/starwind/skeleton";
---

<div class="flex flex-col space-y-3">
  <Skeleton class="h-[125px] w-[250px] rounded-xl" />
  <div class="space-y-2">
    <Skeleton class="h-4 w-[250px]" />
    <Skeleton class="h-4 w-[200px]" />
  </div>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Skeleton } from "@/components/starwind/skeleton";

export function Example() {
  return (
    <>
      <div className="flex flex-col space-y-3">
        <Skeleton className="h-[125px] w-[250px] rounded-xl" />
        <div className="space-y-2">
          <Skeleton className="h-4 w-[250px]" />
          <Skeleton className="h-4 w-[200px]" />
        </div>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Table Skeleton

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Skeleton } from "@/components/starwind/skeleton";
---

<div class="space-y-2 w-[250px]">
  <Skeleton class="h-8 w-full" />
  <Skeleton class="h-8 w-full" />
  <Skeleton class="h-8 w-full" />
  <Skeleton class="h-8 w-full" />
  <Skeleton class="h-8 w-full" />
</div>
```
  </div>
  <div slot="react">
```tsx
import { Skeleton } from "@/components/starwind/skeleton";

export function Example() {
  return (
    <>
      <div className="space-y-2 w-[250px]">
        <Skeleton className="h-8 w-full" />
        <Skeleton className="h-8 w-full" />
        <Skeleton className="h-8 w-full" />
        <Skeleton className="h-8 w-full" />
        <Skeleton className="h-8 w-full" />
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Skeleton
- Inherits div attributes. Omits `children`.

## Changelog

### v1.3.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v1.2.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.2.0

- style updates

### v1.1.0

- Add `data-slot` attribute to enable global styling updates

### v1.0.0

- Initial release with starwind v1.7.0

---

Source: [https://starwind.dev/docs/components/slider/](https://starwind.dev/docs/components/slider/) · [Markdown](https://starwind.dev/docs/components/slider.md)

# Slider

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Slider } from "@/components/starwind/slider";
---

<Slider defaultValue={25} aria-label="Volume" />
```
  </div>
  <div slot="react">
```tsx
import { Slider } from "@/components/starwind/slider";

export function Example() {
  return (
    <>
      <Slider defaultValue={25} aria-label="Volume" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add slider
```

## Usage

### General Notes

The `Slider` component provides an accessible way to select values within a range. It supports:

- **Single value selection**: Default mode with one thumb
- **Range selection**: Pass an array to `defaultValue` for two thumbs
- **Keyboard navigation**: Arrow keys, Page Up/Down, Home/End
- **Form integration**: Works with native form submission via hidden inputs

### Range Slider

Pass an array of two values to create a range slider with two thumbs.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Slider } from "@/components/starwind/slider";
---

<Slider defaultValue={[25, 75]} aria-label="Price range" />
```
  </div>
  <div slot="react">
```tsx
import { Slider } from "@/components/starwind/slider";

export function Example() {
  return (
    <>
      <Slider defaultValue={[25, 75]} aria-label="Price range" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### With Step

Use the `step` prop to control the increment value.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Slider } from "@/components/starwind/slider";
---

<Slider defaultValue={50} step={10} aria-label="Rating" />
```
  </div>
  <div slot="react">
```tsx
import { Slider } from "@/components/starwind/slider";

export function Example() {
  return (
    <>
      <Slider defaultValue={50} step={10} aria-label="Rating" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Variants

The slider supports multiple color variants.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Slider } from "@/components/starwind/slider";
---

<div class="flex flex-col gap-4">
  <Slider defaultValue={50} variant="default" aria-label="Default variant" />
  <Slider defaultValue={50} variant="primary" aria-label="Primary variant" />
  <Slider defaultValue={50} variant="secondary" aria-label="Secondary variant" />
  <Slider defaultValue={50} variant="info" aria-label="Info variant" />
  <Slider defaultValue={50} variant="success" aria-label="Success variant" />
  <Slider defaultValue={50} variant="warning" aria-label="Warning variant" />
  <Slider defaultValue={50} variant="error" aria-label="Error variant" />
</div>
```
  </div>
  <div slot="react">
```tsx
import { Slider } from "@/components/starwind/slider";

export function Example() {
  return (
    <>
      <div className="flex flex-col gap-4">
        <Slider defaultValue={50} variant="default" aria-label="Default variant" />
        <Slider defaultValue={50} variant="primary" aria-label="Primary variant" />
        <Slider defaultValue={50} variant="secondary" aria-label="Secondary variant" />
        <Slider defaultValue={50} variant="info" aria-label="Info variant" />
        <Slider defaultValue={50} variant="success" aria-label="Success variant" />
        <Slider defaultValue={50} variant="warning" aria-label="Warning variant" />
        <Slider defaultValue={50} variant="error" aria-label="Error variant" />
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Disabled

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Slider } from "@/components/starwind/slider";
---

<Slider defaultValue={40} disabled aria-label="Disabled slider" />
```
  </div>
  <div slot="react">
```tsx
import { Slider } from "@/components/starwind/slider";

export function Example() {
  return (
    <>
      <Slider defaultValue={40} disabled aria-label="Disabled slider" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Vertical Orientation

Set `orientation="vertical"` for a vertical slider. Make sure to provide a container with a defined height.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Slider } from "@/components/starwind/slider";
---

<div class="h-32">
  <Slider defaultValue={60} orientation="vertical" aria-label="Vertical slider" />
</div>
```
  </div>
  <div slot="react">
```tsx
import { Slider } from "@/components/starwind/slider";

export function Example() {
  return (
    <>
      <div className="h-32">
        <Slider defaultValue={60} orientation="vertical" aria-label="Vertical slider" />
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Form Submission

The slider includes hidden `<input type="range">` elements for native form submission. For range sliders, the inputs are named with array notation (e.g., `price[0]`, `price[1]`).

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
import { Label } from "@/components/starwind/label";
import { Slider } from "@/components/starwind/slider";
---

<form id="slider-form" class="space-y-4">
  <div class="space-y-2">
    <Label for="volume">Volume</Label>
    <Slider defaultValue={50} name="volume" aria-label="Volume" />
  </div>
  <div class="space-y-2">
    <Label for="price-range">Price Range</Label>
    <Slider defaultValue={[20, 80]} name="price" aria-label="Price range" />
  </div>
  <Button type="submit">Submit</Button>
</form>

export function Example() {
  function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    console.log(Object.fromEntries(new FormData(event.currentTarget).entries()));
  }

return (
    <form className="space-y-4" onSubmit={handleSubmit}>
      <div className="space-y-2">
        <Label htmlFor="volume">Volume</Label>
        <Slider defaultValue={50} name="volume" aria-label="Volume" />
      </div>
      <div className="space-y-2">
        <Label htmlFor="price-range">Price Range</Label>
        <Slider defaultValue={[20, 80]} name="price" aria-label="Price range" />
      </div>
      <Button type="submit">Submit</Button>
    </form>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Slider
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultValue` | `number \| number[]` | No | `0` | Primitive override | Sets the initial value when the component is uncontrolled. |
| `orientation` | `"horizontal" \| "vertical"` | No | `"horizontal"` | Primitive override | Selects the horizontal or vertical layout direction. |
| `value` | `number \| number[]` | No | - | Primitive override | Controls or identifies the component value. |
| `variant` | `"default" \| "primary" \| "secondary" \| "info" \| "success" \| "warning" \| "error"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits div attributes. Omits `defaultValue`, `onChange`, and `value`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Slider Primitive](/docs/primitives/slider/)
- Runtime factory: [`createSlider`](/docs/runtime/#create-slider) from `@starwind-ui/runtime/slider`

## Changelog

### v2.0.1

- Updated React Runtime state synchronization so canceled proposals stay uncommitted and accepted changes remain aligned.

### v2.0.0

- Rebuilt Slider on Starwind Runtime for values, keyboard interaction, dragging, and native form participation.
- See the [Slider Primitive](/docs/primitives/slider/) for the underlying unstyled anatomy and behavior API.

### v1.0.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.13.0

---

Source: [https://starwind.dev/docs/components/spinner/](https://starwind.dev/docs/components/spinner/) · [Markdown](https://starwind.dev/docs/components/spinner.md)

# Spinner

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Spinner } from "@/components/starwind/spinner";
---

<Spinner />
```
  </div>
  <div slot="react">
```tsx
import { Spinner } from "@/components/starwind/spinner";

export function Example() {
  return (
    <>
      <Spinner />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add spinner
```

## Usage

### Custom Size

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Spinner } from "@/components/starwind/spinner";
---

<Spinner class="size-4" />
<Spinner class="size-6" />
<Spinner class="size-8" />
<Spinner class="size-12" />
```
  </div>
  <div slot="react">
```tsx
import { Spinner } from "@/components/starwind/spinner";

export function Example() {
  return (
    <>
      <Spinner className="size-4" />
      <Spinner className="size-6" />
      <Spinner className="size-8" />
      <Spinner className="size-12" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Custom Color

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Spinner } from "@/components/starwind/spinner";
---

<Spinner class="text-blue-500" />
<Spinner class="text-green-500" />
<Spinner class="text-red-500" />
<Spinner class="text-purple-500" />
```
  </div>
  <div slot="react">
```tsx
import { Spinner } from "@/components/starwind/spinner";

export function Example() {
  return (
    <>
      <Spinner className="text-blue-500" />
      <Spinner className="text-green-500" />
      <Spinner className="text-red-500" />
      <Spinner className="text-purple-500" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### In Button

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Spinner } from "@/components/starwind/spinner";
import { Button } from "@/components/starwind/button";
---

<Button disabled>
  <Spinner />
  Loading...
</Button>
```
  </div>
  <div slot="react">
```tsx
import { Spinner } from "@/components/starwind/spinner";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Button disabled>
        <Spinner />
        Loading...
      </Button>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Spinner
- Inherits svg attributes. Omits `aria-label`, `mode`, and `role`.

## Changelog

### v1.1.1

- Removed the conflicting SVG `mode` prop from the Astro and React public prop contracts so fresh
Astro projects type-check cleanly.

### v1.1.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v1.0.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.10.0

---

Source: [https://starwind.dev/docs/components/switch/](https://starwind.dev/docs/components/switch/) · [Markdown](https://starwind.dev/docs/components/switch.md)

# Switch

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Switch } from "@/components/starwind/switch";
---

<Switch id="demo-switch" label="Switch" />
```
  </div>
  <div slot="react">
```tsx
import { Switch } from "@/components/starwind/switch";

export function Example() {
  return (
    <>
      <Switch id="demo-switch" label="Switch" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add switch
```

## Usage

### variant

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Switch } from "@/components/starwind/switch";
---

<Switch id="default" label="Default" variant="default" defaultChecked />
<Switch id="primary" label="Primary" variant="primary" defaultChecked />
<Switch id="secondary" label="Secondary" variant="secondary" defaultChecked />
<Switch id="info" label="Info" variant="info" defaultChecked />
<Switch id="success" label="Success" variant="success" defaultChecked />
<Switch id="warning" label="Warning" variant="warning" defaultChecked />
<Switch id="error" label="Error" variant="error" defaultChecked />
```
  </div>
  <div slot="react">
```tsx
import { Switch } from "@/components/starwind/switch";

export function Example() {
  return (
    <>
      <Switch id="default" label="Default" variant="default" defaultChecked />
      <Switch id="primary" label="Primary" variant="primary" defaultChecked />
      <Switch id="secondary" label="Secondary" variant="secondary" defaultChecked />
      <Switch id="info" label="Info" variant="info" defaultChecked />
      <Switch id="success" label="Success" variant="success" defaultChecked />
      <Switch id="warning" label="Warning" variant="warning" defaultChecked />
      <Switch id="error" label="Error" variant="error" defaultChecked />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### size

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Switch } from "@/components/starwind/switch";
---

<Switch id="small" label="Small" size="sm" />
<Switch id="medium" label="Medium" size="md" />
<Switch id="large" label="Large" size="lg" />
```
  </div>
  <div slot="react">
```tsx
import { Switch } from "@/components/starwind/switch";

export function Example() {
  return (
    <>
      <Switch id="small" label="Small" size="sm" />
      <Switch id="medium" label="Medium" size="md" />
      <Switch id="large" label="Large" size="lg" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Event Handling

Whenever toggled, the Switch root emits `starwind:checked-change`. Read the next state from
`event.detail.checked`.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Switch } from "@/components/starwind/switch";
---

<div class="mt-8 space-y-4">
  <h2 class="text-xl font-semibold">Switch Event Test</h2>

<div id="status-display" class="text-muted-foreground text-sm">
      Switch is currently: <span class="text-foreground font-medium">off</span>
    </div>
  </div>
</div>

root?.addEventListener("starwind:checked-change", (event) => {
    const { checked } = (event as CustomEvent<{ checked: boolean }>).detail;
    if (output) output.textContent = checked ? "on" : "off";
  });
</script>
```
  </div>
  <div slot="react">
```tsx
import { useState } from "react";
import { Switch } from "@/components/starwind/switch";

export function Example() {
  const [checked, setChecked] = useState(false);

return (
    <div className="mt-8 space-y-4">
      <h2 className="text-xl font-semibold">Switch Event Test</h2>
      <div className="space-y-4">
        <Switch
          id="test-switch"
          label="Test Switch"
          variant="primary"
          checked={checked}
          onCheckedChange={setChecked}
        />
        <div className="text-muted-foreground text-sm">
          Switch is currently:{" "}
          <span className="text-foreground font-medium">{checked ? "on" : "off"}</span>
        </div>
      </div>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Switch
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultChecked` | `boolean` | No | - | Primitive override | Sets the initial checked state when the choice is uncontrolled. |
| `id` | `string` | Yes | - | Primitive override | Sets the element id used by labels and related controls. |
| `label` | `string` | No | - | Wrapper prop | Provides accessible text for the component. |
| `padding` | `number` | No | - | Wrapper prop | Sets the component's internal padding. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `variant` | `"primary" \| "secondary" \| "default" \| "info" \| "success" \| "warning" \| "error"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits button attributes. Omits `aria-checked`, `defaultChecked`, `onChange`, `role`, and `type`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Switch Primitive](/docs/primitives/switch/)
- Runtime factory: [`createSwitch`](/docs/runtime/#create-switch) from `@starwind-ui/runtime/switch`

## Changelog

### v2.0.1

- Updated React Runtime state synchronization so canceled proposals stay uncommitted and accepted changes remain aligned.
- Associated the React Switch with its native form owner for submission and reset behavior.

### v2.0.0

- Rebuilt Switch on Starwind Runtime for checked state, native form participation, and checked-change events.
- See the [Switch Primitive](/docs/primitives/switch/) for the underlying unstyled anatomy and behavior API.

### v1.3.3

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.3.1

- Add `starwind:init` event listener to enable initialization of additional Switches loaded after an initial page load, such as when using server islands

### v1.3.0

- style and focus state updates

### v1.2.0

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

### v1.1.0

---

Source: [https://starwind.dev/docs/components/table/](https://starwind.dev/docs/components/table/) · [Markdown](https://starwind.dev/docs/components/table.md)

# Table

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Table, TableHeader, TableHead, TableBody, TableRow, TableCell, TableCaption, TableFoot } from "@/components/starwind/table";
---

<Table class="max-w-md mx-auto">
  <TableCaption>Example of a simple table</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Email</TableHead>
      <TableHead>Status</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Ada Lovelace</TableCell>
      <TableCell>ada@starwind.dev</TableCell>
      <TableCell>Active</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>Grace Hopper</TableCell>
      <TableCell>grace@starwind.dev</TableCell>
      <TableCell>Inactive</TableCell>
    </TableRow>
  </TableBody>
  <TableFoot>
    <TableRow>
      <TableCell colspan="3">Total: 2 users</TableCell>
    </TableRow>
  </TableFoot>
</Table>
```
  </div>
  <div slot="react">
```tsx
import { Table, TableHeader, TableHead, TableBody, TableRow, TableCell, TableCaption, TableFoot } from "@/components/starwind/table";

export function Example() {
  return (
    <>
      <Table className="max-w-md mx-auto">
        <TableCaption>Example of a simple table</TableCaption>
        <TableHeader>
          <TableRow>
            <TableHead>Name</TableHead>
            <TableHead>Email</TableHead>
            <TableHead>Status</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          <TableRow>
            <TableCell>Ada Lovelace</TableCell>
            <TableCell>ada@starwind.dev</TableCell>
            <TableCell>Active</TableCell>
          </TableRow>
          <TableRow>
            <TableCell>Grace Hopper</TableCell>
            <TableCell>grace@starwind.dev</TableCell>
            <TableCell>Inactive</TableCell>
          </TableRow>
        </TableBody>
        <TableFoot>
          <TableRow>
            <TableCell colSpan={3}>Total: 2 users</TableCell>
          </TableRow>
        </TableFoot>
      </Table>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add table
```

## Usage

### Dynamic Data Table Example

Render a table of recent orders using Astro frontmatter and Starwind UI Table components:

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
const orders = [
  { order: "ORD1001", status: "Shipped", total: "$120.00", customer: "Alice Smith" },
  { order: "ORD1002", status: "Processing", total: "$80.00", customer: "Bob Johnson" },
  { order: "ORD1003", status: "Delivered", total: "$200.00", customer: "Charlie Rose" },
  { order: "ORD1004", status: "Cancelled", total: "$50.00", customer: "Dana Lee" },
];
---
<Table>
  <TableCaption>A list of your recent orders.</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead class="w-[120px]">Order</TableHead>
      <TableHead>Status</TableHead>
      <TableHead>Customer</TableHead>
      <TableHead class="text-right">Total</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    {orders.map(order => (
      <TableRow>
        <TableCell class="font-medium">{order.order}</TableCell>
        <TableCell>{order.status}</TableCell>
        <TableCell>{order.customer}</TableCell>
        <TableCell class="text-right">{order.total}</TableCell>
      </TableRow>
    ))}
  </TableBody>
  <TableFoot>
    <TableRow>
      <TableCell colspan="3">Total Orders</TableCell>
      <TableCell class="text-right">$450.00</TableCell>
    </TableRow>
  </TableFoot>
</Table>
```
  </div>
  <div slot="react">
```tsx
import { Table, TableBody, TableCaption, TableCell, TableFoot, TableHead, TableHeader, TableRow } from "@/components/starwind/table";

const orders = [
  { order: "ORD1001", status: "Shipped", total: "$120.00", customer: "Alice Smith" },
  { order: "ORD1002", status: "Processing", total: "$80.00", customer: "Bob Johnson" },
  { order: "ORD1003", status: "Delivered", total: "$200.00", customer: "Charlie Rose" },
  { order: "ORD1004", status: "Cancelled", total: "$50.00", customer: "Dana Lee" },
];

export function Example() {
  return (
    <>
      <Table>
        <TableCaption>A list of your recent orders.</TableCaption>
        <TableHeader>
          <TableRow>
            <TableHead className="w-[120px]">Order</TableHead>
            <TableHead>Status</TableHead>
            <TableHead>Customer</TableHead>
            <TableHead className="text-right">Total</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {orders.map((order) => (
            <TableRow key={order.order}>
              <TableCell className="font-medium">{order.order}</TableCell>
              <TableCell>{order.status}</TableCell>
              <TableCell>{order.customer}</TableCell>
              <TableCell className="text-right">{order.total}</TableCell>
            </TableRow>
          ))}
        </TableBody>
        <TableFoot>
          <TableRow>
            <TableCell colSpan={3}>Total Orders</TableCell>
            <TableCell className="text-right">$450.00</TableCell>
          </TableRow>
        </TableFoot>
      </Table>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Table
- Inherits table attributes.

### TableHeader
- Inherits thead attributes.

### TableBody
- Inherits tbody attributes.

### TableFoot
- Inherits tfoot attributes.

### TableRow
- Inherits tr attributes.

### TableHead
- Inherits th attributes.

### TableCell
- Inherits td attributes.

### TableCaption
- Inherits caption attributes.

## Changelog

### v1.2.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v1.2.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v1.1.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.1.0

- Add a `data-slot` attribute to all components to enable global styling updates, replacing the current `data-table` and similar attributes.

### v1.0.0

- Initial component release with starwind v1.6.0

---

Source: [https://starwind.dev/docs/components/tabs/](https://starwind.dev/docs/components/tabs/) · [Markdown](https://starwind.dev/docs/components/tabs.md)

# Tabs

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/starwind/tabs";
---

<Tabs defaultValue="astro" class="max-w-[400px]">
  <TabsList>
    <TabsTrigger value="astro">Astro</TabsTrigger>
    <TabsTrigger value="next">Next.js</TabsTrigger>
  </TabsList>
  <TabsContent value="astro">
    Build fast websites, faster with Astro's next-gen island architecture.
  </TabsContent>
  <TabsContent value="next">
    The React framework for production-grade applications that scale.
  </TabsContent>
</Tabs>
```
  </div>
  <div slot="react">
```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/starwind/tabs";

export function Example() {
  return (
    <>
      <Tabs defaultValue="astro" className="max-w-[400px]">
        <TabsList>
          <TabsTrigger value="astro">Astro</TabsTrigger>
          <TabsTrigger value="next">Next.js</TabsTrigger>
        </TabsList>
        <TabsContent value="astro">
          Build fast websites, faster with Astro's next-gen island architecture.
        </TabsContent>
        <TabsContent value="next">
          The React framework for production-grade applications that scale.
        </TabsContent>
      </Tabs>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add tabs
```

## Usage

### Synced Tabs

Use the `syncKey` prop to synchronize multiple tab groups. All tabs with the same `syncKey` will update together.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/starwind/tabs";
---

<Tabs defaultValue="react" syncKey="frameworks" class="max-w-[400px]">
  <TabsList>
    <TabsTrigger value="react">React</TabsTrigger>
    <TabsTrigger value="vue">Vue</TabsTrigger>
  </TabsList>
  <TabsContent value="react">
    React is a JavaScript library for building user interfaces.
  </TabsContent>
  <TabsContent value="vue">
    Vue is a progressive framework for building user interfaces.
  </TabsContent>
</Tabs>

<Tabs defaultValue="react" syncKey="frameworks" class="max-w-[400px]">
  <TabsList>
    <TabsTrigger value="react">React</TabsTrigger>
    <TabsTrigger value="vue">Vue</TabsTrigger>
  </TabsList>
  <TabsContent value="react">
    React's virtual DOM optimizes rendering performance.
  </TabsContent>
  <TabsContent value="vue">
    Vue's reactivity system makes state management intuitive.
  </TabsContent>
</Tabs>
```
  </div>
  <div slot="react">
```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/starwind/tabs";

export function Example() {
  return (
    <>
      <Tabs defaultValue="react" syncKey="frameworks" className="max-w-[400px]">
        <TabsList>
          <TabsTrigger value="react">React</TabsTrigger>
          <TabsTrigger value="vue">Vue</TabsTrigger>
        </TabsList>
        <TabsContent value="react">
          React is a JavaScript library for building user interfaces.
        </TabsContent>
        <TabsContent value="vue">
          Vue is a progressive framework for building user interfaces.
        </TabsContent>
      </Tabs>

<Tabs defaultValue="react" syncKey="frameworks" className="max-w-[400px]">
        <TabsList>
          <TabsTrigger value="react">React</TabsTrigger>
          <TabsTrigger value="vue">Vue</TabsTrigger>
        </TabsList>
        <TabsContent value="react">
          React's virtual DOM optimizes rendering performance.
        </TabsContent>
        <TabsContent value="vue">
          Vue's reactivity system makes state management intuitive.
        </TabsContent>
      </Tabs>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Disabled Triggers

Use the `disabled` attribute to prevent a tab from being selected.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/starwind/tabs";
---

<Tabs defaultValue="active" class="max-w-[400px]">
  <TabsList>
    <TabsTrigger value="active">Active</TabsTrigger>
    <TabsTrigger value="disabled" disabled>Disabled</TabsTrigger>
    <TabsTrigger value="pending">Pending</TabsTrigger>
  </TabsList>
  <TabsContent value="active">Active tab content</TabsContent>
  <TabsContent value="disabled">Disabled tab content</TabsContent>
  <TabsContent value="pending">Pending tab content</TabsContent>
</Tabs>
```
  </div>
  <div slot="react">
```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/starwind/tabs";

export function Example() {
  return (
    <>
      <Tabs defaultValue="active" className="max-w-[400px]">
        <TabsList>
          <TabsTrigger value="active">Active</TabsTrigger>
          <TabsTrigger value="disabled" disabled>Disabled</TabsTrigger>
          <TabsTrigger value="pending">Pending</TabsTrigger>
        </TabsList>
        <TabsContent value="active">Active tab content</TabsContent>
        <TabsContent value="disabled">Disabled tab content</TabsContent>
        <TabsContent value="pending">Pending tab content</TabsContent>
      </Tabs>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Nested Tabs

Show how tabs can be nested by placing a Tabs component inside a TabsContent panel.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/starwind/tabs";
---

<Tabs defaultValue="outer-1">
  <TabsList>
    <TabsTrigger value="outer-1">Outer Tab 1</TabsTrigger>
    <TabsTrigger value="outer-2">Outer Tab 2</TabsTrigger>
  </TabsList>
  <TabsContent value="outer-1">
    Outer Tab 1 content
  </TabsContent>
  <TabsContent value="outer-2">
    <div class="space-y-2">
      This tab contains nested tabs:
      <Tabs defaultValue="inner-a">
        <TabsList>
          <TabsTrigger value="inner-a">Inner A</TabsTrigger>
          <TabsTrigger value="inner-b">Inner B</TabsTrigger>
        </TabsList>
        <TabsContent value="inner-a">Inner tab A content</TabsContent>
        <TabsContent value="inner-b">Inner tab B content</TabsContent>
      </Tabs>
    </div>
  </TabsContent>
</Tabs>
```
  </div>
  <div slot="react">
```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/starwind/tabs";

export function Example() {
  return (
    <>
      <Tabs defaultValue="outer-1">
        <TabsList>
          <TabsTrigger value="outer-1">Outer Tab 1</TabsTrigger>
          <TabsTrigger value="outer-2">Outer Tab 2</TabsTrigger>
        </TabsList>
        <TabsContent value="outer-1">
          Outer Tab 1 content
        </TabsContent>
        <TabsContent value="outer-2">
          <div className="space-y-2">
            This tab contains nested tabs:
            <Tabs defaultValue="inner-a">
              <TabsList>
                <TabsTrigger value="inner-a">Inner A</TabsTrigger>
                <TabsTrigger value="inner-b">Inner B</TabsTrigger>
              </TabsList>
              <TabsContent value="inner-a">Inner tab A content</TabsContent>
              <TabsContent value="inner-b">Inner tab B content</TabsContent>
            </Tabs>
          </div>
        </TabsContent>
      </Tabs>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Tabs
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultValue` | `string \| null` | No | - | Primitive override | Sets the initial value when the component is uncontrolled. |
| `orientation` | `"horizontal" \| "vertical"` | No | `"horizontal"` | Primitive override | Selects the horizontal or vertical layout direction. |
| `value` | `string \| null` | No | - | Primitive override | Controls or identifies the component value. |
- Inherits div attributes. Omits `defaultValue`, `onChange`, and `value`.

### TabsList
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `activateOnFocus` | `boolean` | No | - | Primitive override | Activates the focused item while moving through the collection. |
| `loopFocus` | `boolean` | No | - | Primitive override | Wraps keyboard focus from the last item to the first and vice versa. |
- Inherits div attributes.

### TabsTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | `string` | Yes | - | Wrapper prop | Controls or identifies the component value. |
- Inherits button attributes. Omits `type` and `value`.

### TabsContent
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `keepMounted` | `boolean` | No | - | Primitive override | Keeps hidden content mounted in the DOM. |
| `value` | `string` | Yes | - | Wrapper prop | Controls or identifies the component value. |
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Tabs Primitive](/docs/primitives/tabs/)
- Runtime factory: [`createTabs`](/docs/runtime/#create-tabs) from `@starwind-ui/runtime/tabs`

## Changelog

### v2.0.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.0

- Rebuilt Tabs on Starwind Runtime for selection, focus movement, and synchronized groups.
- See the [Tabs Primitive](/docs/primitives/tabs/) for the underlying unstyled anatomy and behavior API.

### v1.4.3

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.4.1

- Add `starwind:init` event listener to enable initialization of additional Tabs loaded after an initial page load, such as when using server islands

### 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

- Add support for nested tabs

### v1.1.1

- Small script cleanup

### v1.1.0

---

Source: [https://starwind.dev/docs/components/textarea/](https://starwind.dev/docs/components/textarea/) · [Markdown](https://starwind.dev/docs/components/textarea.md)

# Textarea

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Textarea } from "@/components/starwind/textarea";
---

<Textarea placeholder="Type something..." />
```
  </div>
  <div slot="react">
```tsx
import { Textarea } from "@/components/starwind/textarea";

export function Example() {
  return (
    <>
      <Textarea placeholder="Type something..." />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add textarea
```

## Usage

### size

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Textarea } from "@/components/starwind/textarea";
---

<Textarea size="sm" placeholder="Small textarea" />
<Textarea size="md" placeholder="Medium textarea" />
<Textarea size="lg" placeholder="Large textarea" />
```
  </div>
  <div slot="react">
```tsx
import { Textarea } from "@/components/starwind/textarea";

export function Example() {
  return (
    <>
      <Textarea size="sm" placeholder="Small textarea" />
      <Textarea size="md" placeholder="Medium textarea" />
      <Textarea size="lg" placeholder="Large textarea" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### disabled

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Textarea } from "@/components/starwind/textarea";
---

<Textarea disabled placeholder="Disabled textarea" />
```
  </div>
  <div slot="react">
```tsx
import { Textarea } from "@/components/starwind/textarea";

export function Example() {
  return (
    <>
      <Textarea disabled placeholder="Disabled textarea" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Textarea
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits textarea attributes. Omits `children`.

## Changelog

### v1.4.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v1.3.3

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.2.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.2.1

- add `aria-invalid` styling

### v1.2.0

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

### v1.1.1

- Adjust component to use type `VariantProps` from `tailwind-variants`. This provides greater type safety and cleans up component frontmatter.

### v1.1.0

---

Source: [https://starwind.dev/docs/components/theme-toggle/](https://starwind.dev/docs/components/theme-toggle/) · [Markdown](https://starwind.dev/docs/components/theme-toggle.md)

# Theme Toggle

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { ThemeToggle } from "@/components/starwind/theme-toggle";
---

<ThemeToggle ariaLabel="Toggle theme" />
```
  </div>
  <div slot="react">
```tsx
import { ThemeToggle } from "@/components/starwind/theme-toggle";

export function Example() {
  return (
    <>
      <ThemeToggle ariaLabel="Toggle theme" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Theme Toggle now uses the shared theme controller from `@starwind-ui/astro/theme`. Controls with
the same sync group stay aligned across navigation and system-theme changes.

## Installation

```bash
npx starwind@latest add theme-toggle
```

## Usage

### Preventing a theme flash

Render `ThemeInitScript` in your document head. It applies the persisted or system theme before
the page becomes visible.

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
---
import { ThemeInitScript } from "@starwind-ui/astro/theme";
---

<html>
  <head>
    <ThemeInitScript />
  </head>
  <body>
    <slot />
  </body>
</html>
```
</div>
<div slot="react">
```tsx
import type { ReactNode } from "react";
import { getThemeInitScript } from "@starwind-ui/react/theme";

function ThemeInitScript() {
  return <script dangerouslySetInnerHTML={{ __html: getThemeInitScript() }} />;
}

export function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html suppressHydrationWarning>
      <head>
        <ThemeInitScript />
      </head>
      <body>{children}</body>
    </html>
  );
}
```
</div>
</FrameworkCodeSwitcher>

### Custom icons

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import Heart from "@tabler/icons/outline/heart.svg";
import Star from "@tabler/icons/outline/star.svg";
import { ThemeToggle } from "@/components/starwind/theme-toggle";
---

<ThemeToggle ariaLabel="Toggle theme with custom icons">
  <Heart
    slot="light-icon"
    class="hidden size-5 group-data-[state=off]:data-ready:block"
    data-theme-icon
  />
  <Star
    slot="dark-icon"
    class="hidden size-5 group-data-[state=on]:data-ready:block"
    data-theme-icon
  />
</ThemeToggle>
```
  </div>
  <div slot="react">
```tsx
import { IconHeart as Heart, IconStar as Star } from "@tabler/icons-react";
import { ThemeToggle } from "@/components/starwind/theme-toggle";

export function Example() {
  return (
    <ThemeToggle
      ariaLabel="Toggle theme with custom icons"
      lightIcon={
        <Heart
          className="hidden size-5 group-data-[state=off]:data-ready:block"
          data-theme-icon
        />
      }
      darkIcon={
        <Star
          className="hidden size-5 group-data-[state=on]:data-ready:block"
          data-theme-icon
        />
      }
    />
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Custom icon visibility follows the Runtime-owned `data-state` and `data-ready` attributes. Keep
`data-theme-icon` on each icon so the controller can synchronize it.

## API Reference
### ThemeToggle
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `ariaLabel` | `string` | No | `"Toggle theme"` | Wrapper prop | Provides an accessible label when visible text is not available. |
| `defaultPressed` | `boolean` | No | - | Wrapper prop | Sets the initial pressed state when the control is uncontrolled. |
| `disabled` | `boolean` | No | `false` | Wrapper prop | Disables interaction with the component. |
| `pressed` | `boolean` | No | - | Wrapper prop | Controls the pressed state. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `syncGroup` | `string` | No | `"starwind-theme"` | Wrapper prop | Synchronizes pressed state across Theme Toggles in the same named group. |
| `value` | `string` | No | - | Wrapper prop | Controls or identifies the component value. |
| `variant` | `"default" \| "outline"` | No | `"outline"` | Styled variant | Selects the component's visual variant. |
- Inherits button attributes. Omits `aria-pressed`, `defaultPressed`, `disabled`, `onChange`, `type`, and `value`.

## Changelog

### v2.0.0

- Added contract-generated Astro and React implementations and replaced page-local storage logic with the shared Runtime theme controller and `ThemeInitScript`.
- See the [Runtime theme reference](/docs/runtime/#theme) for the shared theme behavior and helpers.
- Theme Toggle now uses the shared theme controller from `@starwind-ui/astro/theme`. Controls with
the same sync group stay aligned across Astro navigation and system-theme changes.

---

Source: [https://starwind.dev/docs/components/toast/](https://starwind.dev/docs/components/toast/) · [Markdown](https://starwind.dev/docs/components/toast.md)

# Toast

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
---

<div class="flex flex-wrap gap-2">
  <Button variant="outline" id="toast-demo-default">Default</Button>
  <Button variant="outline" id="toast-demo-success">Success</Button>
  <Button variant="outline" id="toast-demo-error">Error</Button>
</div>

document.getElementById("toast-demo-default")?.addEventListener("click", () => {
    toast("Default Toast");
  });

document.getElementById("toast-demo-success")?.addEventListener("click", () => {
    toast.success("Success!", { description: "Your changes have been saved." });
  });

> **Info:** The styled package supplies the Toaster markup, while imperative notifications now come from the framework primitive entrypoint: `@starwind-ui/astro/toast`.

## Installation

```bash
npx starwind@latest add toast
```

## Usage

### Setup

The `Toaster` component must be added once to your page, usually in a common layout file shared between pages so you can trigger toasts from anywhere.

```astro title="src/layouts/Layout.astro"
<!doctype html>
<html lang="en">
  <head>
    
  </head>
  <body>
    
    <main>
      
    </main>
    <Toaster position="bottom-right" />
  </body>
</html>
```

### Basic Usage

Toasts are created using the `toast` function. Import it in a `<script>` tag and call it to show notifications.

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<Button id="show-toast">Show Toast</Button>

export function Example() {
  return <Button onClick={() => toast("Hello world!")}>Show Toast</Button>;
}
```
</div>
</FrameworkCodeSwitcher>

### Variants

The toast system supports multiple variants for different message types.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
---

<div class="flex flex-wrap gap-2">
  <Button variant="outline" id="toast-default">Default</Button>
  <Button variant="outline" id="toast-success">Success</Button>
  <Button variant="outline" id="toast-error">Error</Button>
  <Button variant="outline" id="toast-warning">Warning</Button>
  <Button variant="outline" id="toast-info">Info</Button>
  <Button variant="outline" id="toast-loading">Loading</Button>
</div>

document.getElementById("toast-default")?.addEventListener("click", () => {
    toast("Default Toast");
  });

document.getElementById("toast-success")?.addEventListener("click", () => {
    toast.success("Success!", {
      description: "Your changes have been saved.",
    });
  });

document.getElementById("toast-error")?.addEventListener("click", () => {
    toast.error("Error", {
      description: "Something went wrong.",
    });
  });

document.getElementById("toast-warning")?.addEventListener("click", () => {
    toast.warning("Warning", {
      description: "Please review your input.",
    });
  });

document.getElementById("toast-info")?.addEventListener("click", () => {
    toast.info("Info", {
      description: "Here's some helpful information.",
    });
  });

export function Example() {
  return (
    <div className="flex flex-wrap gap-2">
      <Button variant="outline" onClick={() => toast("Default Toast")}>Default</Button>
      <Button
        variant="outline"
        onClick={() => toast.success("Success!", { description: "Your changes have been saved." })}
      >
        Success
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.error("Error", { description: "Something went wrong." })}
      >
        Error
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.warning("Warning", { description: "Please review your input." })}
      >
        Warning
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.info("Info", { description: "Here's some helpful information." })}
      >
        Info
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.loading("Loading...", { description: "Please wait while we process your request." })}
      >
        Loading
      </Button>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Promise Toast

Handle async operations with automatic loading, success, and error states.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
---

<div class="flex flex-wrap gap-2">
  <Button variant="primary" id="toast-promise-success">Promise (Success)</Button>
  <Button variant="error" id="toast-promise-error">Promise (Error)</Button>
</div>

document.getElementById("toast-promise-success")?.addEventListener("click", () => {
    const fakeApiCall = async () => {
      await new Promise((resolve) => setTimeout(resolve, 2000));
      return { name: "John" };
    };

toast.promise(fakeApiCall(), {
      loading: { title: "Saving...", description: "Please wait" },
      success: (data) => ({ title: "Saved!", description: `Welcome, ${data.name}!` }),
      error: { title: "Error", description: "Failed to save" },
    });
  });

document.getElementById("toast-promise-error")?.addEventListener("click", () => {
    const fakeApiCall = async () => {
      await new Promise((resolve) => setTimeout(resolve, 2000));
      throw new Error("Network error");
    };

toast
      .promise(fakeApiCall(), {
        loading: "Processing...",
        success: "Done!",
        error: (err) => ({
          title: err.message || "Contact support for assistance",
          description: "Pardon our dust while we fix this issue.",
        }),
      })
      .catch(() => {});
  });
</script>
```
  </div>
  <div slot="react">
```tsx
import { Button } from "@/components/starwind/button";
import { toast } from "@starwind-ui/react/toast";

async function successfulRequest() {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  return { name: "John" };
}

async function failedRequest() {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  throw new Error("Network error");
}

export function Example() {
  return (
    <div className="flex flex-wrap gap-2">
      <Button
        variant="primary"
        onClick={() => {
          void toast.promise(successfulRequest(), {
            loading: { title: "Saving...", description: "Please wait" },
            success: (data) => ({ title: "Saved!", description: "Welcome, " + data.name + "!" }),
            error: { title: "Error", description: "Failed to save" },
          });
        }}
      >
        Promise (Success)
      </Button>
      <Button
        variant="error"
        onClick={() => {
          void toast
            .promise(failedRequest(), {
              loading: "Processing...",
              success: "Done!",
              error: (error) => ({
                title: error instanceof Error ? error.message : "Contact support for assistance",
                description: "Pardon our dust while we fix this issue.",
              }),
            })
            .catch(() => {});
        }}
      >
        Promise (Error)
      </Button>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Updating & Dismissing

You can update existing toasts or dismiss them programmatically.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Button } from "@/components/starwind/button";
---

<div class="flex flex-wrap gap-2">
  <Button variant="outline" id="toast-update">Create & Update</Button>
  <Button variant="outline" id="toast-dismiss-all">Dismiss All</Button>
</div>

document.getElementById("toast-update")?.addEventListener("click", () => {
    const id = toast("Processing...", { description: "Step 1 of 3" });

setTimeout(() => {
      toast.update(id, { title: "Still working...", description: "Step 2 of 3" });
    }, 1500);

setTimeout(() => {
      toast.update(id, {
        title: "Complete!",
        description: "All steps finished",
        variant: "success",
      });
    }, 3000);
  });

export function Example() {
  return (
    <div className="flex flex-wrap gap-2">
      <Button variant="outline" onClick={createAndUpdateToast}>Create & Update</Button>
      <Button variant="outline" onClick={() => toast.dismiss()}>Dismiss All</Button>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Toaster
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `gap` | `string` | No | `"0.5rem"` | Wrapper prop | Sets the space between repeated items. |
| `peek` | `string` | No | `"1rem"` | Wrapper prop | Sets how much of an adjacent item remains visible. |
- Inherits div attributes.

### ToastTemplate
- Inherits div attributes.

### ToastItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `"default" \| "success" \| "error" \| "warning" \| "info"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits div attributes.

### ToastContent
- Inherits div attributes.

### ToastTitle
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `"default" \| "success" \| "error" \| "warning" \| "info" \| "loading"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits div attributes.

### ToastDescription
- Inherits div attributes.

### ToastAction
- Inherits button attributes.

### ToastClose
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `showIcon` | `boolean` | No | `true` | Wrapper prop | Shows the component's generated icon. |
- Inherits button attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Toast Primitive](/docs/primitives/toast/)
- Runtime factory: [`createToastManager`](/docs/runtime/#create-toast-manager) from `@starwind-ui/runtime/toast`

## Changelog

### v2.0.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.0

- Rebuilt Toast on Starwind Runtime for manager state, templates, updates, dismissal, and lifecycle.
- See the [Toast Primitive](/docs/primitives/toast/) for the underlying unstyled anatomy and behavior API.
- The styled package supplies the Toaster markup, while imperative notifications now come from the framework primitive entrypoint: `@starwind-ui/astro/toast`.

---

Source: [https://starwind.dev/docs/components/toggle/](https://starwind.dev/docs/components/toggle/) · [Markdown](https://starwind.dev/docs/components/toggle.md)

# Toggle

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Toggle } from "@/components/starwind/toggle";
---

<Toggle variant="outline">Toggle</Toggle>
```
  </div>
  <div slot="react">
```tsx
import { Toggle } from "@/components/starwind/toggle";

export function Example() {
  return (
    <>
      <Toggle variant="outline">Toggle</Toggle>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add toggle
```

## Usage

### variant

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Toggle } from "@/components/starwind/toggle";
---

<Toggle variant="default">Default</Toggle>
<Toggle variant="outline">Outline</Toggle>
```
  </div>
  <div slot="react">
```tsx
import { Toggle } from "@/components/starwind/toggle";

export function Example() {
  return (
    <>
      <Toggle variant="default">Default</Toggle>
      <Toggle variant="outline">Outline</Toggle>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### size

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Toggle } from "@/components/starwind/toggle";
---

<Toggle size="sm">Small</Toggle>
<Toggle size="md">Medium</Toggle>
<Toggle size="lg">Large</Toggle>
```
  </div>
  <div slot="react">
```tsx
import { Toggle } from "@/components/starwind/toggle";

export function Example() {
  return (
    <>
      <Toggle size="sm">Small</Toggle>
      <Toggle size="md">Medium</Toggle>
      <Toggle size="lg">Large</Toggle>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### syncGroup

Use the `syncGroup` prop to keep multiple toggles in sync. When one toggle in the group is pressed, all toggles with the same `syncGroup` will mirror its state.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Toggle } from "@/components/starwind/toggle";
---

<Toggle variant="outline" syncGroup="view-mode">
  Grid view
</Toggle>
<Toggle variant="outline" syncGroup="view-mode">
  Grid view (mirrored)
</Toggle>
```
  </div>
  <div slot="react">
```tsx
import { Toggle } from "@/components/starwind/toggle";

export function Example() {
  return (
    <>
      <Toggle variant="outline" syncGroup="view-mode">
        Grid view
      </Toggle>
      <Toggle variant="outline" syncGroup="view-mode">
        Grid view (mirrored)
      </Toggle>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Event Handling

Whenever toggled, the Toggle root emits `starwind:pressed-change`. Read the next state from
`event.detail.pressed`.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Toggle } from "@/components/starwind/toggle";
---

<div class="space-y-4">
  <Toggle id="test-toggle">Test Toggle</Toggle>

<div id="status-display" class="text-muted-foreground text-sm">
    Toggle is currently: <span class="text-foreground font-medium">off</span>
  </div>
</div>

root?.addEventListener("starwind:pressed-change", (event) => {
    const { pressed } = (event as CustomEvent<{ pressed: boolean }>).detail;
    if (output) output.textContent = pressed ? "on" : "off";
  });
</script>
```
  </div>
  <div slot="react">
```tsx
import { useState } from "react";
import { Toggle } from "@/components/starwind/toggle";

export function Example() {
  const [pressed, setPressed] = useState(false);

return (
    <div className="space-y-4">
      <Toggle pressed={pressed} onPressedChange={setPressed}>Test Toggle</Toggle>
      <div className="text-muted-foreground text-sm">
        Toggle is currently:{" "}
        <span className="text-foreground font-medium">{pressed ? "on" : "off"}</span>
      </div>
    </div>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Toggle
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultPressed` | `boolean` | No | - | Primitive override | Sets the initial pressed state when the control is uncontrolled. |
| `nativeButton` | `boolean` | No | - | Primitive override | Uses native button semantics for the interactive control. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `variant` | `"default" \| "outline"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits button attributes. Omits `aria-pressed`, `defaultPressed`, `disabled`, `onChange`, `type`, and `value`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Toggle Primitive](/docs/primitives/toggle/)
- Runtime factory: [`createToggle`](/docs/runtime/#create-toggle) from `@starwind-ui/runtime/toggle`

## Changelog

### v2.0.1

- Updated React Runtime state synchronization so canceled proposals stay uncommitted and accepted changes remain aligned.

### v2.0.0

- Rebuilt Toggle on Starwind Runtime for pressed state and pressed-change events.
- See the [Toggle Primitive](/docs/primitives/toggle/) for the underlying unstyled anatomy and behavior API.

### v1.0.3

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.1

- Add `starwind:init` event listener to enable initialization of additional Toggles loaded after an initial page load, such as when using server islands

### v1.0.0

- Initial release with starwind v1.12.0

---

Source: [https://starwind.dev/docs/components/toggle-group/](https://starwind.dev/docs/components/toggle-group/) · [Markdown](https://starwind.dev/docs/components/toggle-group.md)

# Toggle Group

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";
---

<ToggleGroup defaultValue={["bold"]} aria-label="Text formatting">
  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
  <ToggleGroupItem value="underline">Underline</ToggleGroupItem>
</ToggleGroup>
```
  </div>
  <div slot="react">
```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";

export function Example() {
  return (
    <>
      <ToggleGroup defaultValue={["bold"]} aria-label="Text formatting">
        <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
        <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
        <ToggleGroupItem value="underline">Underline</ToggleGroupItem>
      </ToggleGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add toggle-group
```

## Usage

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
<ToggleGroup multiple defaultValue={["left", "center"]} variant="outline">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>
```
  </div>
  <div slot="react">
```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";

export function Example() {
  return (
    <>
      <ToggleGroup multiple defaultValue={["left", "center"]} variant="outline">
        <ToggleGroupItem value="left">Left</ToggleGroupItem>
        <ToggleGroupItem value="center">Center</ToggleGroupItem>
        <ToggleGroupItem value="right">Right</ToggleGroupItem>
      </ToggleGroup>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Sizes

`ToggleGroup` is the sole size owner. Set `size="sm"`, `size="md"` (the default), or `size="lg"`
on the root; items still support independent `variant` overrides but no longer accept `size`.

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<ToggleGroup size="sm" defaultValue={["left"]} aria-label="Small alignment">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
</ToggleGroup>

<ToggleGroup size="lg" defaultValue={["left"]} aria-label="Large alignment">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center" variant="outline">Center</ToggleGroupItem>
</ToggleGroup>
```
</div>
<div slot="react">
```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";

export function Example() {
  return (
    <>
      <ToggleGroup size="sm" defaultValue={["left"]} aria-label="Small alignment">
        <ToggleGroupItem value="left">Left</ToggleGroupItem>
        <ToggleGroupItem value="center">Center</ToggleGroupItem>
      </ToggleGroup>

<ToggleGroup size="lg" defaultValue={["left"]} aria-label="Large alignment">
        <ToggleGroupItem value="left">Left</ToggleGroupItem>
        <ToggleGroupItem value="center" variant="outline">Center</ToggleGroupItem>
      </ToggleGroup>
    </>
  );
}
```
</div>
</FrameworkCodeSwitcher>

### Size migration

| Before | After |
| --- | --- |
| `<ToggleGroup><ToggleGroupItem size="sm" /></ToggleGroup>` | `<ToggleGroup size="sm"><ToggleGroupItem /></ToggleGroup>` |

## API Reference
### ToggleGroup
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultValue` | `string[]` | No | - | Primitive override | Sets the initial value when the component is uncontrolled. |
| `loopFocus` | `boolean` | No | - | Primitive override | Wraps keyboard focus from the last item to the first and vice versa. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Wrapper prop | Selects the component's visual size. |
| `spacing` | `number` | No | `2` | Wrapper prop | Sets the space between grouped controls. |
| `variant` | `"default" \| "outline"` | No | `"default"` | Wrapper prop | Selects the component's visual variant. |
- Inherits div attributes. Omits `defaultValue` and `onChange`.

### ToggleGroupItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultPressed` | `boolean` | No | - | Primitive override | Sets the initial pressed state when the control is uncontrolled. |
| `nativeButton` | `boolean` | No | - | Primitive override | Uses native button semantics for the interactive control. |
| `variant` | `"default" \| "outline"` | No | - | Wrapper prop | Selects the component's visual variant. |
- Inherits button attributes. Omits `aria-pressed`, `defaultPressed`, `disabled`, `onChange`, `type`, and `value`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Toggle Primitive](/docs/primitives/toggle/)
- Primitive: [Toggle Group Primitive](/docs/primitives/toggle-group/)
- Runtime factory: [`createToggle`](/docs/runtime/#create-toggle) from `@starwind-ui/runtime/toggle`
- Runtime factory: [`createToggleGroup`](/docs/runtime/#create-toggle-group) from `@starwind-ui/runtime/toggle-group`

## Changelog

### v2.0.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.0

- Removed `ToggleGroupItem.size`; `ToggleGroup` now exclusively owns the shared item size.
- Migration: move every item-level `size` value to its containing `ToggleGroup`. Per-item
`variant` overrides continue to work.

### v1.0.0

- Added Toggle Group as a Runtime-backed component with grouped toggle state.
- See the [Toggle Primitive](/docs/primitives/toggle/) and [Toggle Group Primitive](/docs/primitives/toggle-group/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/tooltip/](https://starwind.dev/docs/components/tooltip/) · [Markdown](https://starwind.dev/docs/components/tooltip.md)

# Tooltip

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/starwind/tooltip";
import { Button } from "@/components/starwind/button";
---

<Tooltip>
  <TooltipTrigger>
    <Button variant="outline">Hover me</Button>
  </TooltipTrigger>
  <TooltipContent>
    Add to library
  </TooltipContent>
</Tooltip>
```
  </div>
  <div slot="react">
```tsx
import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/starwind/tooltip";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Tooltip>
        <TooltipTrigger>
          <Button variant="outline">Hover me</Button>
        </TooltipTrigger>
            <TooltipContent>
              Add to library
            </TooltipContent>
      </Tooltip>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add tooltip
```

## Usage

### Positioning

Control the position and alignment of the tooltip using the `side` and `align` props.

<Tooltip>
  <TooltipTrigger>
    <Button variant="outline">Top</Button>
  </TooltipTrigger>
  <TooltipContent>
    Tooltip on top
  </TooltipContent>
</Tooltip>

<Tooltip>
  <TooltipTrigger>
    <Button variant="outline">Right</Button>
  </TooltipTrigger>
  <TooltipContent side="right">
    Tooltip on right
  </TooltipContent>
</Tooltip>

<Tooltip>
  <TooltipTrigger>
    <Button variant="outline">Bottom</Button>
  </TooltipTrigger>
  <TooltipContent side="bottom">
    Tooltip on bottom
  </TooltipContent>
</Tooltip>

<Tooltip>
  <TooltipTrigger>
    <Button variant="outline">Left</Button>
  </TooltipTrigger>
  <TooltipContent side="left">
    Tooltip on left
  </TooltipContent>
</Tooltip>
```
  </div>
  <div slot="react">
```tsx
import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/starwind/tooltip";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Tooltip>
        <TooltipTrigger>
          <Button variant="outline">Top</Button>
        </TooltipTrigger>
        <TooltipContent>
          Tooltip on top
        </TooltipContent>
      </Tooltip>

<Tooltip>
        <TooltipTrigger>
          <Button variant="outline">Right</Button>
        </TooltipTrigger>
        <TooltipContent side="right">
          Tooltip on right
        </TooltipContent>
      </Tooltip>

<Tooltip>
        <TooltipTrigger>
          <Button variant="outline">Bottom</Button>
        </TooltipTrigger>
        <TooltipContent side="bottom">
          Tooltip on bottom
        </TooltipContent>
      </Tooltip>

<Tooltip>
        <TooltipTrigger>
          <Button variant="outline">Left</Button>
        </TooltipTrigger>
        <TooltipContent side="left">
          Tooltip on left
        </TooltipContent>
      </Tooltip>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Delay

Customize the open and close delay using the `openDelay` and `closeDelay` props.

<Tooltip openDelay={0} closeDelay={500}>
  <TooltipTrigger>
    <Button variant="outline">No open delay</Button>
  </TooltipTrigger>
  <TooltipContent>
    Instant tooltip
  </TooltipContent>
</Tooltip>

<Tooltip openDelay={1000}>
  <TooltipTrigger>
    <Button variant="outline">Slow open</Button>
  </TooltipTrigger>
  <TooltipContent>
    Opens after 1 second
  </TooltipContent>
</Tooltip>
```
  </div>
  <div slot="react">
```tsx
import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/starwind/tooltip";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Tooltip openDelay={0} closeDelay={500}>
        <TooltipTrigger>
          <Button variant="outline">No open delay</Button>
        </TooltipTrigger>
        <TooltipContent>
          Instant tooltip
        </TooltipContent>
      </Tooltip>

<Tooltip openDelay={1000}>
        <TooltipTrigger>
          <Button variant="outline">Slow open</Button>
        </TooltipTrigger>
        <TooltipContent>
          Opens after 1 second
        </TooltipContent>
      </Tooltip>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### Alignment

Control the alignment of the tooltip relative to its trigger using the `align` prop.

<div class="flex justify-between w-[300px]">
  <Tooltip>
    <TooltipTrigger>
      <Button variant="outline">Start</Button>
    </TooltipTrigger>
    <TooltipContent align="start">
      Aligned to start
    </TooltipContent>
  </Tooltip>

<Tooltip>
    <TooltipTrigger>
      <Button variant="outline">Center</Button>
    </TooltipTrigger>
    <TooltipContent align="center">
      Aligned to center
    </TooltipContent>
  </Tooltip>

<Tooltip>
    <TooltipTrigger>
      <Button variant="outline">End</Button>
    </TooltipTrigger>
    <TooltipContent align="end">
      Aligned to end
    </TooltipContent>
  </Tooltip>
</div>

<div class="flex justify-between w-[300px]">
  <Tooltip>
    <TooltipTrigger>
      <Button variant="outline">Bottom Start</Button>
    </TooltipTrigger>
    <TooltipContent side="bottom" align="start">
      Bottom aligned to start
    </TooltipContent>
  </Tooltip>

<Tooltip>
    <TooltipTrigger>
      <Button variant="outline">Bottom End</Button>
    </TooltipTrigger>
    <TooltipContent side="bottom" align="end">
      Bottom aligned to end
    </TooltipContent>
  </Tooltip>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/starwind/tooltip";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <div className="flex justify-between w-[300px]">
        <Tooltip>
          <TooltipTrigger>
            <Button variant="outline">Start</Button>
          </TooltipTrigger>
          <TooltipContent align="start">
            Aligned to start
          </TooltipContent>
        </Tooltip>

<Tooltip>
          <TooltipTrigger>
            <Button variant="outline">Center</Button>
          </TooltipTrigger>
          <TooltipContent align="center">
            Aligned to center
          </TooltipContent>
        </Tooltip>

<Tooltip>
          <TooltipTrigger>
            <Button variant="outline">End</Button>
          </TooltipTrigger>
          <TooltipContent align="end">
            Aligned to end
          </TooltipContent>
        </Tooltip>
      </div>

<div className="flex justify-between w-[300px]">
        <Tooltip>
          <TooltipTrigger>
            <Button variant="outline">Bottom Start</Button>
          </TooltipTrigger>
          <TooltipContent side="bottom" align="start">
            Bottom aligned to start
          </TooltipContent>
        </Tooltip>

<Tooltip>
          <TooltipTrigger>
            <Button variant="outline">Bottom End</Button>
          </TooltipTrigger>
          <TooltipContent side="bottom" align="end">
            Bottom aligned to end
          </TooltipContent>
        </Tooltip>
      </div>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Tooltip
- Inherits div attributes.

### TooltipTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `true` | Primitive override | Merges the component behavior and props into its child element. |
- Inherits span attributes.

### TooltipContent
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `positionerClass` | `string` | No | - | Wrapper prop | Adds classes to the generated floating positioner element. |
- Inherits div attributes. Omits `tabIndex` and `tabindex`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Tooltip Primitive](/docs/primitives/tooltip/)
- Runtime factory: [`createTooltip`](/docs/runtime/#create-tooltip) from `@starwind-ui/runtime/tooltip`

## Changelog

### v2.1.0

- Added `positionerClass` to `TooltipContent` so the floating positioner can be styled directly.
- Moved the default stacking level from the content to the positioner.

### v2.0.2

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.0

- Rebuilt Tooltip on Starwind Runtime for hover and focus timing, floating placement, and dismissal.
- See the [Tooltip Primitive](/docs/primitives/tooltip/) for the underlying unstyled anatomy and behavior API.

---

Source: [https://starwind.dev/docs/components/video/](https://starwind.dev/docs/components/video/) · [Markdown](https://starwind.dev/docs/components/video.md)

# Video

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import navVideo from "@/assets/videos/starwind-pro_nav-3-responsive.mp4";
import { Video } from "@/components/starwind/video";
---

<Video src={navVideo} controls muted class="rounded-lg" />
```
  </div>
  <div slot="react">
```tsx
import navVideo from "@/assets/videos/starwind-pro_nav-3-responsive.mp4";
import { Video } from "@/components/starwind/video";

export function Example() {
  return (
    <>
      <Video src={navVideo} controls muted className="rounded-lg" />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add video
```

## Usage

### General Notes

The `Video` component automatically detects the video type from the source URL and renders either a native HTML5 `<video>` element or a YouTube `<iframe>` embed. It supports:

- **Native videos**: Local files, imported assets, or direct video URLs
- **YouTube videos**: Standard YouTube URLs, short URLs, and embed URLs
- **YouTube Shorts**: Automatically detected and rendered with appropriate settings

### YouTube Video

Pass a YouTube URL directly to the `src` prop. The component handles URL parsing and creates a privacy-enhanced embed using `youtube-nocookie.com`.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Video } from "@/components/starwind/video";
---

<Video
  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  title="YouTube video"
  class="rounded-lg"
/>
```
  </div>
  <div slot="react">
```tsx
import { Video } from "@/components/starwind/video";

export function Example() {
  return (
    <>
      <Video
        src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
        title="YouTube video"
        className="rounded-lg"
      />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

### YouTube Shorts

YouTube Shorts are automatically detected and rendered appropriately. Use custom aspect ratio classes to display them correctly.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Video } from "@/components/starwind/video";
---

<Video
  src="https://www.youtube.com/shorts/WVfUcdYugio"
  title="YouTube Shorts"
  class="aspect-square max-w-xs rounded-lg"
/>
```
  </div>
  <div slot="react">
```tsx
import { Video } from "@/components/starwind/video";

export function Example() {
  return (
    <>
      <Video
        src="https://www.youtube.com/shorts/WVfUcdYugio"
        title="YouTube Shorts"
        className="aspect-square max-w-xs rounded-lg"
      />
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Video
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `autoplay` | `boolean` | No | `false` | Wrapper prop | Starts media playback automatically when supported by the browser. |
| `controls` | `boolean` | No | `true` | Wrapper prop | Shows the browser's native media controls. |
| `loop` | `boolean` | No | `false` | Wrapper prop | Restarts media playback after it reaches the end. |
| `muted` | `boolean` | No | `false` | Wrapper prop | Starts or renders media with audio muted. |
| `poster` | `string` | No | - | Wrapper prop | Provides the image displayed before video playback starts. |
| `src` | `string` | Yes | - | Wrapper prop | Provides the media source URL. |
| `title` | `string` | No | `"Video"` | Wrapper prop | Provides an accessible title for embedded media. |
- Inherits iframe attributes.
- Inherits video attributes.

## Changelog

### v1.1.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.

### v1.0.2

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.13.0

---

Source: [https://starwind.dev/docs/frameworks/astro/](https://starwind.dev/docs/frameworks/astro/) · [Markdown](https://starwind.dev/docs/frameworks/astro.md)

# Astro Installation

This guide covers Astro 5 and newer. Starwind uses the Astro adapter and the standard `src/`
project layout.

## Requirements

- Astro 5 or newer.
- A project root with `package.json` and an `astro.config.ts`, `.js`, `.mjs`, or `.cjs` file.
- A shared layout or page that can own the Starwind stylesheet and theme initializer.

## Create an Astro Project

Skip this step when the Astro project already exists.

```bash
npm create astro@latest
```

## Initialize Starwind

Run the command from the project root.

```bash
npx starwind@latest init --defaults
```

Starwind detects Astro from `package.json` or an Astro configuration file. It installs
`@starwind-ui/astro`, creates `starwind.config.json`, configures the `@/*` alias, adds the Tailwind
Vite plugin, and creates these default paths:

| Purpose | Path |
| --- | --- |
| Styled components | `src/components/starwind` |
| Shared utilities | `src/lib/utils` |
| Starwind stylesheet | `src/styles/starwind.css` |

When `src/layouts/Layout.astro` or `src/layouts/BaseLayout.astro` exists, initialization imports the
stylesheet there. The minimal Astro starter has no shared layout, so its first page must own the
stylesheet and theme initializer. Move those two concerns into your shared layout when you add one.

## Add and Render Button

```bash
npx starwind@latest add button
```

The following example works as-is in the minimal Astro starter:

```astro title="src/pages/index.astro"
<html lang="en">
  <head>
    <ThemeInitScript />
  </head>
  <body>
    <Button>Hello from Astro</Button>
  </body>
</html>
```

## Manual Setup Details

Manual setup uses the same paths and adapter. Install `@starwind-ui/astro` with the dependencies
listed in the generated registry setup, create the common Starwind stylesheet described in
[Theming](/docs/getting-started/theming/), and configure the project as follows.

### Alias

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```

### Tailwind Vite plugin

```js title="astro.config.mjs"
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "astro/config";

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});
```

### Stylesheet and theme initialization

Import the stylesheet and render `ThemeInitScript` in the document head. The script applies the
saved theme before paint and supports Astro view transitions.

```astro title="src/layouts/Layout.astro"
---
import { ThemeInitScript } from "@starwind-ui/astro/theme";
import "@/styles/starwind.css";
---

<!doctype html>
<html lang="en">
  <head>
    <ThemeInitScript />
  </head>
  <body>
    <slot />
  </body>
</html>
```

See [Dark Mode](/docs/getting-started/dark-mode/#astro) for theme controls and configuration.

## React Islands

The Astro adapter renders native `.astro` components. An Astro project can also keep React-targeted
Starwind source for React islands. Initialize that secondary target explicitly:

```bash
npx starwind@latest init --framework react --defaults
```

Starwind detects the Astro host, installs Astro's React integration and the React adapter, then
keeps Astro as the primary config framework. React components go in
`src/components/starwind-react` through `componentDirs.react`.

Add a component to the React target and hydrate it as an island:

```bash
npx starwind@latest add button --framework react
```

```astro title="src/pages/index.astro"
---
import { ThemeInitScript } from "@starwind-ui/react/theme";
import { Button } from "@/components/starwind-react/button";
import "@/styles/starwind.css";
---

<html lang="en">
  <head>
    <ThemeInitScript />
  </head>
  <body>
    <Button client:load>Hello from a React island</Button>
  </body>
</html>
```

This flow also adds `@astrojs/react`, React, React DOM, and the required JSX compiler settings when
the Astro project does not already use React.

## Support Boundaries

Automatic setup supports the standard Astro `src/` layout and an Astro config that exports an
object-form `defineConfig({ ... })` call. Keep one Starwind theme initializer and stylesheet import
in the shared document owner.

---

Source: [https://starwind.dev/docs/frameworks/nextjs/](https://starwind.dev/docs/frameworks/nextjs/) · [Markdown](https://starwind.dev/docs/frameworks/nextjs.md)

# Next.js Installation

Starwind supports both Next.js routing systems. The CLI detects the active router and whether the
application uses a root-level or `src/` source tree.

## Requirements

- React and React DOM 18 or newer.
- A Next.js project with an App Router root layout or a Pages Router custom App.
- A supported global stylesheet for the selected router.

## Create a Next.js Project

Skip this step when the project already exists.

```bash
npx create-next-app@latest my-app --yes
```

The current recommended defaults create an App Router project with TypeScript, Tailwind CSS,
and the `@/*` alias. Add `--src-dir` when you want `src/app`.
</DocsTabsContent>
```bash
npx create-next-app@latest my-app --no-app --yes
```

The explicit `--no-app` flag selects the Pages Router while `--yes` accepts the remaining
recommended defaults.
</DocsTabsContent>
</DocsTabs>

## Initialize Starwind

```bash
cd my-app
npx starwind@latest init --defaults
```

Starwind reads the `next` and `react` dependencies, then checks the router files before it installs
packages or changes the project. The resulting `starwind.config.json` keeps `framework: "react"`;
the detected Next.js router controls the file plan.

## App Router

Starwind recognizes `app/layout.*` and `src/app/layout.*`. It looks for the global stylesheet in
the matching source tree, creates components and utilities beside that tree, and imports the
Starwind stylesheet from the global stylesheet.

| Source tree | Components | Utilities | Starwind stylesheet |
| --- | --- | --- | --- |
| Root `app/` | `components/starwind` | `lib/utils` | `styles/starwind.css` |
| `src/app/` | `src/components/starwind` | `src/lib/utils` | `src/styles/starwind.css` |

Initialization adds `ThemeInitScript` to the root layout head and adds
`suppressHydrationWarning` to `<html>`. The prepaint script resolves the saved theme before React
hydrates.

```tsx title="app/layout.tsx"
import { ThemeInitScript } from "@starwind-ui/react/theme";

import "./globals.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeInitScript />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

Add and render `Button` from an App Router page:

```bash
npx starwind@latest add button
```

```tsx title="app/page.tsx"
import { Button } from "@/components/starwind/button";

export default function Page() {
  return <Button>Hello from the App Router</Button>;
}
```

App Router pages are Server Components by default. Generated interactive Starwind components own
their client boundary where their implementation needs one. Add `"use client"` to your component
when your own code uses client-only React APIs such as state or event handlers.

### App Router manual setup

Use `@starwind-ui/react`, configure Tailwind CSS v4 through the Next.js PostCSS integration, and
create the common stylesheet described in [Theming](/docs/getting-started/theming/). The global
stylesheet must import it.

```css title="app/globals.css"
@import "../styles/starwind.css";

/* Application styles */
```

Set `@/*` to `./src/*` for a `src/` tree or `./*` for a root tree. Place `ThemeInitScript` in the
root layout head as shown above.

## Pages Router

Starwind recognizes `pages/_app.*` and `src/pages/_app.*`. The custom App owns the one global CSS

| Source tree | Components | Utilities | Starwind stylesheet |
| --- | --- | --- | --- |
| Root `pages/` | `components/starwind` | `lib/utils` | `styles/starwind.css` |
| `src/pages/` | `src/components/starwind` | `src/lib/utils` | `src/styles/starwind.css` |

Initialization adds the Starwind stylesheet to the existing global stylesheet used by `_app`. It
updates an existing `_document.*` with `ThemeInitScript`, or creates `_document` beside `_app` when
one does not exist.

```tsx title="pages/_app.tsx"
import type { AppProps } from "next/app";

import "@/styles/globals.css";

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}
```

```tsx title="pages/_document.tsx"
import { ThemeInitScript } from "@starwind-ui/react/theme";
import { Head, Html, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html suppressHydrationWarning>
      <Head>
        <ThemeInitScript />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}
```

Add and render `Button` from a page:

```bash
npx starwind@latest add button
```

```tsx title="pages/index.tsx"
import { Button } from "@/components/starwind/button";

export default function Home() {
  return <Button>Hello from the Pages Router</Button>;
}
```

### Pages Router component styles

Next.js Pages requires global component CSS to flow through `_app`. Some generated components have
a local `styles.css` file. Starwind removes those local JavaScript imports and maintains their CSS
imports inside the configured Starwind stylesheet between these markers:

```css
/* Starwind Next.js Pages component styles: start */
@import "../components/starwind/example/styles.css";
/* Starwind Next.js Pages component styles: end */
```

Keep that managed block in place. The CLI updates it when components are added, updated, or removed.

## Support Boundaries

Automatic setup requires one complete supported router shape. An App Router project needs its root
layout and global stylesheet. A Pages Router project needs `_app` and a global stylesheet. Starwind
stops during preflight when these files are incomplete.

See [Dark Mode](/docs/getting-started/dark-mode/#nextjs) for theme behavior in both routers.

---

Source: [https://starwind.dev/docs/frameworks/react-router/](https://starwind.dev/docs/frameworks/react-router/) · [Markdown](https://starwind.dev/docs/frameworks/react-router.md)

# React Router Installation

This guide covers React Router framework mode. A normal Vite SPA that uses React Router as a
library follows the [Vite React guide](/docs/frameworks/vite-react/).

## Requirements

- React and React DOM 18 or newer.
- `react-router.config.*` and `vite.config.*`.
- `app/root.*` and an existing `app/app.css`, `app/root.css`, or `app/styles.css` file.
- The existing `@tailwindcss/vite` plugin in the Vite configuration.

## Create a React Router Project

Skip this step when the framework-mode project already exists.

```bash
npx create-react-router@latest my-app
```

## Initialize Starwind

```bash
cd my-app
npx starwind@latest init --defaults
```

Starwind uses `react-router.config.*` to distinguish framework mode from a Vite SPA. It validates
the Vite config, root route, and global stylesheet before it changes the project.

| Purpose | Path |
| --- | --- |
| Styled components | `app/components/starwind` |
| Shared utilities | `app/lib/utils` |
| Starwind stylesheet | `app/styles/starwind.css` |
| Theme initialization owner | `app/root.*` |

The `@/*` alias points at the `app/` source root, so `@/components/starwind/button` resolves to
`app/components/starwind/button`.

## Add and Render Button

```bash
npx starwind@latest add button
```

```tsx title="app/routes/home.tsx"
import { Button } from "@/components/starwind/button";

export default function Home() {
  return <Button>Hello from React Router</Button>;
}
```

## Manual Setup Details

Use `@starwind-ui/react`, set `@/*` to `./app/*`, and create the shared stylesheet documented in
[Theming](/docs/getting-started/theming/). The existing Vite configuration must include React
Router and Tailwind.

```ts title="vite.config.ts"
import tailwindcss from "@tailwindcss/vite";
import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [tailwindcss(), reactRouter()],
  resolve: {
    tsconfigPaths: true,
  },
});
```

Import the Starwind stylesheet through the existing app stylesheet.

```css title="app/app.css"
@import "./styles/starwind.css";

/* Existing application styles remain here. */
```

Render `ThemeInitScript` in the root document head.

```tsx title="app/root.tsx"
import { ThemeInitScript } from "@starwind-ui/react/theme";
import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeInitScript />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

export default function App() {
  return <Outlet />;
}
```

Initialization preserves an existing Starwind theme initializer and the existing CSS import order.

## Support Boundaries

Automatic setup expects React Router framework mode with Vite and the Tailwind Vite plugin already
configured. Declarative and data-mode Vite SPAs use the
[Vite React guide](/docs/frameworks/vite-react/). Starwind rejects an incomplete framework host
during preflight, before package installation or project mutation.

See [Dark Mode](/docs/getting-started/dark-mode/#react-router) for theme controls.

---

Source: [https://starwind.dev/docs/frameworks/tanstack-start/](https://starwind.dev/docs/frameworks/tanstack-start/) · [Markdown](https://starwind.dev/docs/frameworks/tanstack-start.md)

# TanStack Start Installation

Starwind supports TanStack Start with Vite. The CLI does not configure the Rsbuild starter path.

## Requirements

- React and React DOM 18 or newer.
- `@tanstack/react-start` in the project dependencies.
- `vite.config.*` with the existing `@tailwindcss/vite` plugin.
- `src/routes/__root.*` and an existing `src/styles.css` or `src/app.css` stylesheet.

## Create a TanStack Start Project

Skip this step when the project already exists. The current TanStack CLI creates a Vite-backed
Start project and includes Tailwind CSS in its default starter.

```bash
npx @tanstack/cli@latest create my-app
```

## Initialize Starwind

```bash
cd my-app
npx starwind@latest init --defaults
```

Starwind detects `@tanstack/react-start`, the Vite config, `src/routes/__root.*`, and the global
stylesheet before it changes the project. It installs the React adapter and uses these paths:

| Purpose | Path |
| --- | --- |
| Styled components | `src/components/starwind` |
| Shared utilities | `src/lib/utils` |
| Starwind stylesheet | `src/styles/starwind.css` |
| Theme initialization owner | `src/routes/__root.*` |

The CLI imports the Starwind stylesheet into the existing global stylesheet. Existing `@charset`
and `@import` rules remain in place. The direct `@import "tailwindcss"` rule moves into the shared
Starwind stylesheet so Tailwind is loaded once.

## Add and Render Button

```bash
npx starwind@latest add button
```

```tsx title="src/routes/index.tsx"
import { createFileRoute } from "@tanstack/react-router";

import { Button } from "@/components/starwind/button";

export const Route = createFileRoute("/")({
  component: Home,
});

function Home() {
  return <Button>Hello from TanStack Start</Button>;
}
```

## Manual Setup Details

Use `@starwind-ui/react`, set `@/*` to `./src/*`, and create the common stylesheet from
[Theming](/docs/getting-started/theming/). Keep the framework's existing Vite plugins. The current
starter config includes the following plugin order:

```ts title="vite.config.ts"
import tailwindcss from "@tailwindcss/vite";
import { devtools } from "@tanstack/devtools-vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  resolve: { tsconfigPaths: true },
  plugins: [devtools(), tailwindcss(), tanstackStart(), viteReact()],
});
```

Import Starwind from the existing application stylesheet.

```css title="src/styles.css"
@import "./styles/starwind.css";

/* Existing application styles remain here. */
```

The current starter already places an equivalent inline prepaint script before `HeadContent`. Keep
that existing script. When the root document has no theme initializer, place `ThemeInitScript`
before `HeadContent` as shown here.

```tsx title="src/routes/__root.tsx"
import { ThemeInitScript } from "@starwind-ui/react/theme";
import { createRootRoute, HeadContent, Scripts } from "@tanstack/react-router";

export const Route = createRootRoute({
  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeInitScript />
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}
```

Initialization preserves an existing Starwind `ThemeInitScript`. It also recognizes the previous
inline Starwind prepaint script and avoids adding a second initializer. Keep one theme
initialization owner in the root document.

## Support Boundaries

The automatic setup path requires Vite and an existing `@tailwindcss/vite` plugin. It rejects an
incomplete Start project before package installation or file changes. Rsbuild-based TanStack Start
projects are outside the current CLI support boundary.

See [Dark Mode](/docs/getting-started/dark-mode/#tanstack-start) for theme controls.

---

Source: [https://starwind.dev/docs/frameworks/vite-react/](https://starwind.dev/docs/frameworks/vite-react/) · [Markdown](https://starwind.dev/docs/frameworks/vite-react.md)

# Vite React Installation

This guide covers a standard Vite application with React 18 or newer. It also applies when React
Router is used as a client-side library inside that Vite application.

## Requirements

- React and React DOM 18 or newer.
- A supported `vite.config.*` file.
- A `src/main.tsx`, `.jsx`, `.ts`, or `.js` entry file.
- A global stylesheet imported by the application.

## Create a Vite React Project

Skip this step when the project already exists.

```bash
npm create vite@latest my-app -- --template react-ts
```

## Initialize Starwind

```bash
cd my-app
npx starwind@latest init --defaults
```

Starwind detects React from `package.json`, then confirms the Vite host through `vite.config.*` and
`src/main.*`. It installs `@starwind-ui/react`, creates `starwind.config.json`, configures the
`@/*` alias, updates the Vite plugin list, and imports the Starwind stylesheet from the React entry.
For a JavaScript starter, it also creates `tsconfig.json` with `allowJs` and JSX settings so the
generated TypeScript component source can compile beside `.js` and `.jsx` application files.

| Purpose | Path |
| --- | --- |
| Styled components | `src/components/starwind` |
| Shared utilities | `src/lib/utils` |
| Starwind stylesheet | `src/styles/starwind.css` |

## Add and Render Button

```bash
npx starwind@latest add button
```

```tsx title="src/App.tsx"
import { Button } from "@/components/starwind/button";

export default function App() {
  return <Button>Hello from Vite</Button>;
}
```

## Manual Setup Details

Install `@starwind-ui/react` and the shared dependencies, then create the Starwind stylesheet from
the [Theming guide](/docs/getting-started/theming/). The Vite config needs Tailwind, the `@` alias,
and a prepaint theme plugin based on `getThemeInitScript`.

```ts title="vite.config.ts"
import { fileURLToPath } from "node:url";

import { getThemeInitScript } from "@starwind-ui/react/theme";
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

function starwindThemeInitPlugin() {
  return {
    name: "starwind-theme-init",
    transformIndexHtml() {
      return [
        {
          tag: "script",
          attrs: { "data-starwind-theme-init": "" },
          children: getThemeInitScript(),
          injectTo: "head-prepend" as const,
        },
      ];
    },
  };
}

export default defineConfig({
  resolve: {
    alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) },
  },
  plugins: [starwindThemeInitPlugin(), tailwindcss(), react()],
});
```

Add the matching TypeScript alias to `tsconfig.app.json` when that file exists.

```json title="tsconfig.app.json"
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

Import the generated stylesheet from the detected entry file.

```tsx title="src/main.tsx"
import "@/styles/starwind.css";
```

See [Dark Mode](/docs/getting-started/dark-mode/#vite-react) for the theme API.

## Support Boundaries

The automatic Vite update expects an object-form `defineConfig({ ... })` export with a plugin array
that Starwind can update. A Vite SPA that uses React Router in declarative or data mode stays on
this guide. React Router framework mode has a separate
[React Router guide](/docs/frameworks/react-router/).

---

Source: [https://starwind.dev/docs/getting-started/](https://starwind.dev/docs/getting-started/) · [Markdown](https://starwind.dev/docs/getting-started.md)

# Welcome to Starwind UI

Starwind UI is a layered component system for Astro, React, and plain HTML. Start by rendering a styled component. Reach for Primitive adapters, Runtime APIs, raw HTML, or component-level customization only when you need that level of control.

> **Info:** The beginner path is still source-first: add a styled component, render it, and customize the code in your app.

[Choose your framework](/docs/getting-started/installation/#choose-your-framework) to open the
Astro, Vite React, Next.js, TanStack Start, and React Router installation guides.

## Start With A Styled Component

Install the project defaults, add `Button`, and render it in your app.

```astro
<Button>Hello World</Button>
```

For most projects this is the right first step. The styled component owns the public Starwind ergonomics, styling variants, and default markup for your framework.

## Choose Your Path

- **Styled components**: Use the CLI and component docs when you want ready-to-render UI that you can edit in your project.
- **Primitive adapter**: Use `@starwind-ui/astro` or `@starwind-ui/react` when you want behavior and anatomy without the styled wrapper.
- **Runtime/raw HTML**: Use `@starwind-ui/runtime` and `initStarwind` when you are rendering static markup or integrating outside a framework adapter.
- **Theming and component APIs**: Use the Theming guide for tokens and component pages for slots, variants, and state selectors.

## Naming Rule

Styled components are named for Starwind ergonomics; primitives are named for behavior and anatomy.

That means a styled component can combine multiple primitives, rename a primitive, or have no primitive at all. Component pages identify that Behavior Foundation and link to the lower-level references so you can follow the relationship without leaving the styled docs.

## Deeper References

- [Installation](/docs/getting-started/installation/) covers recommended CLI initialization, current manual setup, and the first rendered styled component.
- [Primitives](/docs/getting-started/primitives/) explains package imports, vendored source, ownership, and framework targeting.
- [Primitive API Reference](/docs/primitives/) is the behavior-first reference for individual Primitive adapters.
- [Runtime And Raw HTML](/docs/runtime/) documents low-level Runtime APIs and the raw HTML surface.
- [Theming](/docs/getting-started/theming/) covers CSS variables, Tailwind integration, and theme customization.
- Component pages cover slots, variants, state selectors, and any framework-specific guidance that affects how you use a styled component.
- [Migration Guide](/docs/getting-started/migration/) explains how the old Astro styled-component docs map into the layered model.

## Glossary

- **Styled adapter contract**: The generated contract that connects a styled component to framework support, exported files, variants, slots, and any behavior foundation.
- **Primitive adapter**: A framework package such as `@starwind-ui/astro` or `@starwind-ui/react` that renders Runtime-backed behavior and anatomy.
- **Runtime**: The framework-agnostic package that owns DOM behavior, state, events, cleanup, and theme helpers.
- **raw HTML surface**: Static markup that uses `data-sw-*` discovery hooks and is initialized by the Runtime.

---

Source: [https://starwind.dev/docs/getting-started/ai/](https://starwind.dev/docs/getting-started/ai/) · [Markdown](https://starwind.dev/docs/getting-started/ai.md)

# AI Integration

Starwind UI exposes public AI-readable surfaces for assistants, editors, and MCP clients. Use this
page as the overview, then jump to [Skills](/docs/getting-started/skills/) or
[MCP Server](/docs/getting-started/mcp/) when you need setup instructions.

<span class="sr-only">If you're an AI assistant reading this documentation, use MCP for a targeted current lookup or validated command when it is available. Use Starwind Skills for project editing rules. Use a per-page `.md` URL for one docs page, `llms.txt` for compact discovery, `ai-manifest.json` for structured inventory and framework availability, and `llms-full.txt` for broad static context.</span>

## Choose a Surface

| Need | Surface |
| --- | --- |
| Current targeted lookup or validated command | [MCP Server](/docs/getting-started/mcp/) |
| Project editing rules | [Skills](/docs/getting-started/skills/) |
| One documentation page | Per-page Markdown |
| Compact discovery | `llms.txt` |
| Structured inventory and framework availability | `ai-manifest.json` |
| Broad static context | `llms-full.txt` |

## AI Reference Files

Starwind UI publishes static text references and a generated JSON manifest from this docs site.

### `llms.txt`

`llms.txt` is a concise static overview for AI tools. It includes the core project description,
important docs links, the installable styled component list, Starwind layers, framework guides,

```txt
https://starwind.dev/llms.txt
```

### `llms-full.txt`

`llms-full.txt` is the full static reference. It includes styled component, Primitive, and Runtime
APIs, framework availability, broader setup guidance, usage examples, theming notes, and CLI
reference material.

```txt
https://starwind.dev/llms-full.txt
```

### `ai-manifest.json`

`ai-manifest.json` is a generated JSON manifest for AI tools. It lists installable components,
styled, Primitive, and Runtime mappings, framework availability, documented patterns, guides,
Skills metadata, MCP metadata, and the current docs URL conventions.

```txt
https://starwind.dev/ai-manifest.json
```

## Per-page Markdown Docs

Every published docs page is also available as Markdown. Simply append `.md` to the docs path.

For example:

```txt
https://starwind.dev/docs/components/button.md
```

HTML docs pages include a Markdown alternate link that points to the `.md` URL.

## Skills

Starwind Skills are installed agent instructions for working with Starwind UI v3 and Starwind Pro.
They teach compatible AI tools how to select a layer, follow Astro or React conventions, use the
CLI, read current docs, compose forms and components, migrate projects, and update customized files
safely.

See [Skills](/docs/getting-started/skills/) for installation and usage details.

## MCP Server

The Starwind UI MCP server is available as `@starwind-ui/mcp`. It prepares validated initialization
commands for Astro and React projects, searches styled components, Primitives, and Pro blocks,
generates install commands, fetches current docs, and checks legacy Astro migrations.

See [MCP Server](/docs/getting-started/mcp/) for client configuration, supported tools, and client
links.

## Feedback

If you encounter any issues or have suggestions for how we can make Starwind UI more usable with AI
tools, please [open an issue](https://github.com/starwind-ui/starwind-ui/issues) in the GitHub
repository.

---

Source: [https://starwind.dev/docs/getting-started/cli/](https://starwind.dev/docs/getting-started/cli/) · [Markdown](https://starwind.dev/docs/getting-started/cli.md)

# Command Line Interface

The Starwind CLI initializes Astro and supported React framework hosts, installs Runtime-backed
styled components, manages optional Primitive source, and configures Starwind Pro. Run it from your
project root with your package manager:

Starwind v3 is stable on npm's `latest` tag. The commands on this page name that tag explicitly.

```bash
npx starwind@latest init
```

The examples below use the installed `starwind` executable for brevity. You can replace it with
the matching package-runner form above.

## init

Use `init` to create `starwind.config.json`, choose Astro or React, install the matching adapter,
create the Starwind CSS file, and configure the project integration and path aliases.

```bash
starwind init
starwind init --framework react
starwind init --astro
starwind init --defaults
```

| Option                    | Description                                      |
| ------------------------- | ------------------------------------------------ |
| `-d, --defaults`          | Use default values for all prompts.              |
| `-p, --pro`               | Initialize the project and configure Pro access. |
| `--framework <framework>` | Select `astro` or `react`.                        |
| `--astro`                 | Initialize for Astro.                            |
| `--react`                 | Initialize for React.                            |

Choose only one of `--framework`, `--astro`, or `--react`. If the project has a legacy config,
`init` offers to run migration before continuing.

### Supported projects

| Project host | Required project signal | Default source root | Guide |
| --- | --- | --- | --- |
| Astro | `astro` dependency or `astro.config.*` | `src` | [Astro](/docs/frameworks/astro/) |
| Vite React | `react`, `vite.config.*`, and `src/main.*` | `src` | [Vite React](/docs/frameworks/vite-react/) |
| Next.js App Router | `next` and `app/layout.*` or `src/app/layout.*` | `.` or `src` | [Next.js](/docs/frameworks/nextjs/#app-router) |
| Next.js Pages Router | `next` and `pages/_app.*` or `src/pages/_app.*` | `.` or `src` | [Next.js](/docs/frameworks/nextjs/#pages-router) |
| TanStack Start with Vite | `@tanstack/react-start`, `vite.config.*`, and `src/routes/__root.*` | `src` | [TanStack Start](/docs/frameworks/tanstack-start/) |
| React Router framework mode | `react-router.config.*`, `vite.config.*`, and `app/root.*` | `app` | [React Router](/docs/frameworks/react-router/) |

### Detection and preflight

With `init --defaults`, Starwind examines `package.json` and framework configuration before it
selects Astro or React. Astro wins when an Astro dependency or config is present, including an
Astro project that also uses React islands. A React dependency selects the public React adapter,
then host detection resolves Vite, Next.js App Router, Next.js Pages Router, TanStack Start, or
React Router framework mode.

Inside an Astro project, `init --framework react --defaults` configures React as a secondary target.
It installs Astro's React integration, writes React components to
`src/components/starwind-react`, and keeps Astro as the primary config framework.

The public adapter value written to `starwind.config.json` is `react` for every React host. The host
is a detected project plan that controls source roots, CSS ownership, theme placement, and package
integration. It is not a separate config framework value.

Starwind validates the host shape before it installs adapter packages, creates directories, writes
configuration, or changes application files. Unsupported or incomplete hosts stop at this
preflight step with the missing integration point in the error message.

## migrate

Use `migrate` to move an existing pre-Runtime Astro project to the Runtime setup.

```bash
starwind migrate
starwind migrate --yes --package-manager pnpm
```

Migration can back up the existing component folders, asks before overwriting conflicts, and keeps
components that cannot be migrated marked as legacy. It migrates all safe components in one run;
it does not accept individual component names.

| Option                       | Description                                    |
| ---------------------------- | ---------------------------------------------- |
| `-y, --yes`                  | Skip confirmation prompts.                     |
| `-m, --package-manager <pm>` | Use `npm`, `pnpm`, or `yarn` for dependencies. |

## add

Use `add` to install Runtime-backed styled component source for the configured framework. With no
component names, the CLI opens an interactive picker.

```bash
starwind add button dropdown
starwind add button --framework react
starwind add --all
```

The CLI resolves component dependencies and package requirements. A framework override installs
the selected Astro or React target; the project config determines its destination.

| Option                       | Description                                    |
| ---------------------------- | ---------------------------------------------- |
| `-a, --all`                  | Add every available uninstalled component.     |
| `-y, --yes`                  | Skip confirmation prompts.                     |
| `-o, --overwrite`            | Overwrite files that already exist.            |
| `--framework <framework>`    | Install the `astro` or `react` target.          |
| `-m, --package-manager <pm>` | Use `npm`, `pnpm`, or `yarn` for dependencies. |

## update

Use `update` to refresh installed styled component source. Updating can overwrite local component
changes, so inspect or commit your changes first. With no names, the CLI opens a picker for the
selected framework.

```bash
starwind update button
starwind update button --framework react
starwind update --all --framework all
starwind update --all --dry-run
```

| Option                       | Description                                               |
| ---------------------------- | --------------------------------------------------------- |
| `-a, --all`                  | Update all installed components in scope.                 |
| `-y, --yes`                  | Skip confirmation prompts.                                |
| `--dry-run`                  | Preview changes without writing files.                    |
| `--diff [path]`              | Show the planned diff for all files or one file.          |
| `--view [path]`              | Show new contents for all planned files or one file.      |
| `--framework <framework>`    | Target `astro`, `react`, or `all`.                         |
| `-m, --package-manager <pm>` | Use `npm`, `pnpm`, or `yarn` for required package updates. |

## Framework targeting

The framework selected by `starwind init` is the primary styled component target. Its source is
written to `componentDir`. When a project intentionally keeps Astro and React styled source side by
side, pass `--framework` to `add` or `update`:

```bash
starwind add button --framework react
starwind update button --framework react
starwind update --all --framework all
```

Additional targets use `componentDirs.<framework>`, such as
`componentDirs.react = "src/components/starwind-react"` in an Astro-primary project. The framework
flag changes the installed source target and destination; it does not create separate component
documentation.

## primitives

Use the `primitives` namespace when you want compile-ready Primitive adapter source in your project
instead of importing only from `@starwind-ui/astro` or `@starwind-ui/react`.

```bash
starwind primitives add button checkbox
starwind primitives add button --framework react --to src/react-primitives
starwind primitives update button
starwind primitives list --framework all
```

### primitives add options

| Option                       | Description                                         |
| ---------------------------- | --------------------------------------------------- |
| `-a, --all`                  | Add all available primitives.                       |
| `-y, --yes`                  | Skip confirmation prompts.                          |
| `-o, --overwrite`            | Overwrite files that already exist.                 |
| `--framework <framework>`    | Target `astro` or `react`.                           |
| `--to <dir>`                 | Set the Primitive source destination.               |
| `-p, --path <dir>`           | Alias for `--to`.                                   |
| `-m, --package-manager <pm>` | Use `npm`, `pnpm`, or `yarn` for dependencies.      |

`primitives update` accepts `--all`, `--yes`, `--dry-run`, `--diff [path]`, `--view [path]`,
`--framework <framework>` (`astro` or `react`), and `--package-manager <pm>`.

`primitives list` accepts `--json` and `--framework <framework>` (`astro`, `react`, or `all`).

See [Primitives](/docs/getting-started/primitives/) for package imports, vendored-source ownership,
framework targeting, and destination guidance. The CLI does not currently provide primitive
remove/export commands, Runtime source add/eject commands, `starwind add --primitives`, or
`starwind update --primitives`.

## search

Search styled components, Starwind Pro blocks, or Primitive source before installing.

```bash
starwind search dropdown
starwind search hero --plan free --limit 5
starwind search --primitives button --framework react
starwind search button --json
```

| Option                    | Description                                      |
| ------------------------- | ------------------------------------------------ |
| `-p, --plan <plan>`       | Filter Pro blocks by `free` or `pro`.            |
| `-c, --category <value>`  | Filter Pro blocks by category.                   |
| `-l, --limit <number>`    | Limit results; defaults to `20` and caps at `50`. |
| `-o, --offset <number>`   | Offset paginated results; defaults to `0`.       |
| `--json`                  | Print structured JSON output.                    |
| `--primitives`            | Search Primitive source.                         |
| `--framework <framework>` | For Primitive search, use `astro`, `react`, or `all`. |

## docs

Use `docs` to open documentation for one or more styled components. Use `--json` when a tool or
script needs the documentation references as structured output.

```bash
starwind docs button dialog
starwind docs button --json
```

## remove

Use `remove` to delete installed styled component source and update `starwind.config.json`. With no
names, the CLI opens an interactive picker.

```bash
starwind remove button
starwind remove button --framework react
starwind remove --all --framework all
```

| Option                    | Description                                    |
| ------------------------- | ---------------------------------------------- |
| `-a, --all`               | Remove every installed component in scope.    |
| `--framework <framework>` | Target `astro`, `react`, or `all`.             |

Check project imports before removing a component. Removal always asks for confirmation.

## setup

Starwind Pro is the CLI's supported setup workflow. For a new project that needs paid Pro
authorization, configure it during initialization:

```bash
starwind init --pro
```

For an existing project, use `setup`. Pro is currently the only setup task, so `setup` and
`setup --pro` perform the same Pro configuration.

```bash
starwind setup
starwind setup --pro
starwind setup --yes --package-manager pnpm
```

| Option                       | Description                                    |
| ---------------------------- | ---------------------------------------------- |
| `-p, --pro`                  | Configure Starwind Pro (currently the default). |
| `-y, --yes`                  | Skip confirmation prompts.                     |
| `-m, --package-manager <pm>` | Use `npm`, `pnpm`, or `yarn` if initialization is needed. |

Setup ensures the project is initialized, configures paid authorization in `starwind.config.json`,
creates or updates `.env.local` with a `STARWIND_LICENSE_KEY` placeholder, and ensures the env file
is ignored by Git. Replace the placeholder with your license key, then install the exact block name
returned by search or the Pro catalog:

```bash
starwind add @starwind-pro/component-name
```

Free `@starwind-pro/*` blocks can be installed after ordinary `starwind init`; they do not require
`init --pro`, `setup`, or a license key. Paid blocks require the authorization configured by
`init --pro` or `setup`. Use `--overwrite` with `add` only when existing Pro block files should be
replaced.

---

Source: [https://starwind.dev/docs/getting-started/dark-mode/](https://starwind.dev/docs/getting-started/dark-mode/) · [Markdown](https://starwind.dev/docs/getting-started/dark-mode.md)

# Dark Mode

Starwind UI components support light and dark themes out of the box. Dark styles use Tailwind
CSS's `dark:` variant and become active when the `dark` class is present on the `<html>` element.

Starwind's shared theme controller manages that class, persists the user's preference, follows
system color-scheme changes, and keeps theme controls synchronized.

## Add Theme Initialization

### Astro

Render `ThemeInitScript` in your main layout's `<head>`. It applies the saved or system theme
before the page becomes visible, preventing a flash of the wrong theme.

```astro title="src/layouts/Layout.astro"
<!doctype html>
<html lang="en">
  <head>
    
    <ThemeInitScript />
  </head>
  <body>
    <slot />
  </body>
</html>
```

By default, `ThemeInitScript`:

- reads and writes the `colorTheme` key in `localStorage`;
- accepts `light`, `dark`, or `system` as the saved preference;
- uses `system` when no preference has been saved; and
- toggles the `dark` class on `<html>` based on the resolved theme.

It also reapplies the theme after Astro view transitions, so no additional
`astro:after-swap` listener is needed.

> **Info:** `system` remains the saved preference while the resolved theme follows
`window.matchMedia("(prefers-color-scheme: dark)")`. Once the shared theme controller is active,
it updates the page when the operating system preference changes.

### Vite React

Vite React uses `getThemeInitScript` from `@starwind-ui/react/theme`. The Starwind CLI adds a small
Vite `transformIndexHtml` plugin that places the script at the start of the document head. This
applies the theme before React renders. See the
[Vite React placement and config](/docs/frameworks/vite-react/#manual-setup-details).

### Next.js

The App Router renders `ThemeInitScript` in `app/layout.*` or `src/app/layout.*`. The Pages Router
renders it in `pages/_document.*` or `src/pages/_document.*`; Starwind creates `_document` when it
is absent. Both use `ThemeInitScript` from `@starwind-ui/react/theme` and set
`suppressHydrationWarning` on the root HTML element. See the
[Next.js App Router](/docs/frameworks/nextjs/#app-router) and
[Next.js Pages Router](/docs/frameworks/nextjs/#pages-router) sections.

### TanStack Start

TanStack Start renders `ThemeInitScript` in `src/routes/__root.*`, immediately before
`HeadContent`. Keep one prepaint script in the root document. Initialization recognizes an
existing Starwind initializer and avoids adding a duplicate. See the
[TanStack Start theme setup](/docs/frameworks/tanstack-start/#manual-setup-details).

### React Router

React Router framework mode renders `ThemeInitScript` in the `<head>` owned by `app/root.*`. The
root `<html>` element receives `suppressHydrationWarning`. See the
[React Router root setup](/docs/frameworks/react-router/#manual-setup-details).

## Customize the defaults

Pass the same settings to the initializer and any controller you initialize manually. The defaults
work for most Starwind projects.

```astro
<ThemeInitScript storageKey="colorTheme" defaultTheme="system" className="dark" />
```

| Prop | Default | Description |
| --- | --- | --- |
| `storageKey` | `"colorTheme"` | The `localStorage` key used for the saved preference. |
| `defaultTheme` | `"system"` | The preference used when no valid saved value exists. |
| `className` | `"dark"` | The class applied to `<html>` when the resolved theme is dark. |

## Add a theme control

Use Starwind UI's [Theme Toggle](/docs/components/theme-toggle/) component for a ready-to-use
light/dark control. It initializes the shared controller, updates the saved preference and `<html>`
class, and synchronizes other theme controls on the page.

```astro
---
import { ThemeToggle } from "@/components/starwind/theme-toggle";
---

<ThemeToggle ariaLabel="Toggle theme" />
```

The toggle switches between `light` and `dark`. Use the lower-level theme controller when your UI
needs an explicit three-way light, dark, and system picker or needs to change the theme
imperatively.

```ts
import { initThemeController } from "@starwind-ui/astro/theme";

const theme = initThemeController();

theme.setTheme("system");
theme.setTheme("dark");
```

> **Tip:** You can find advanced production-ready theme switchers on [Starwind Pro](https://pro.starwind.dev/components/theme-switcher/).

---

Source: [https://starwind.dev/docs/getting-started/installation/](https://starwind.dev/docs/getting-started/installation/) · [Markdown](https://starwind.dev/docs/getting-started/installation.md)

# Installation

Starwind configures an existing Astro or React framework project. Create the application with its
official starter first, then run Starwind from the project root.

## Quick Start

`init --defaults` examines the project before it selects the Astro or React adapter, file locations,
and framework integration.

Starwind v3 is stable and published on npm's `latest` tag. The commands below install the
Runtime-backed Astro and React setup documented on this site.

```bash
npx starwind@latest init --defaults
```

## Choose Your Framework

The `starwind init` command will auto-detect and configure supported frameworks. Full guides can be found below.

<div class="not-sw-prose my-6 grid grid-cols-1 items-stretch gap-4 md:grid-cols-2">
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/astro/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <AstroIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Astro</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/vite-react/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <ViteIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Vite React</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/nextjs/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <NextJsIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Next.js</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/tanstack-start/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <TanStackIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">TanStack Start</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/react-router/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <RouteIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">React Router</span>
</a>
</div>

## What Starwind Adds

- The framework adapter is `@starwind-ui/astro` or `@starwind-ui/react`. React hosts share the
public `react` adapter value in `starwind.config.json`.
- `starwind.config.json` records the registry, adapter, stylesheet, component directory, utility
directory, and installed component versions.
- Styled components are copied into your application. You own their source and can edit it.
- The common Starwind stylesheet provides Tailwind CSS v4, design tokens, dark mode, animation
utilities, and shared component styles.

## Manual Setup

The framework guides explain the supported project shape and the manual integration points for
aliases, CSS entry files, Tailwind, and theme initialization. They reference the shared stylesheet
instead of repeating it. Start with [Theming](/docs/getting-started/theming/) when you need the full
token and stylesheet model.

## Add a Component

After initialization, install `Button` from the styled registry.

```bash
npx starwind@latest add button
```

## Render the Component

<DocsTabs syncKey="adapter" defaultValue="astro">
<DocsTabsList>
<DocsTabsTrigger value="astro">Astro</DocsTabsTrigger>
<DocsTabsTrigger value="react">React</DocsTabsTrigger>
</DocsTabsList>
<DocsTabsContent value="astro">
```astro
---
import { Button } from "@/components/starwind/button";
---

<Button>Hello World</Button>
```
</DocsTabsContent>
<DocsTabsContent value="react">
```tsx
import { Button } from "@/components/starwind/button";

export function Example() {
  return <Button>Hello World</Button>;
}
```
</DocsTabsContent>
</DocsTabs>

## Go Deeper

- [CLI](/docs/getting-started/cli/) documents detection, commands, and options.
- [Theming](/docs/getting-started/theming/) explains the common stylesheet and design tokens.
- [Dark Mode](/docs/getting-started/dark-mode/) explains theme initialization and controls.
- [Primitives](/docs/getting-started/primitives/) covers adapter packages and vendored Primitive
source.
- [Runtime And Raw HTML](/docs/runtime/) covers the framework-independent Runtime APIs.

---

Source: [https://starwind.dev/docs/getting-started/mcp/](https://starwind.dev/docs/getting-started/mcp/) · [Markdown](https://starwind.dev/docs/getting-started/mcp.md)

# MCP Server

Use the Starwind UI MCP server to search Starwind UI, read current documentation, and generate
validated CLI commands from an MCP-compatible assistant. It supports Starwind UI v3 projects using
Astro or React.

The server is published as [@starwind-ui/mcp](https://www.npmjs.com/package/@starwind-ui/mcp) and
runs locally through your MCP client.

## Quick Start

Select your MCP client and add the configuration.

<DocsTabs defaultValue="codex" syncKey="ide" class="min-h-[150px]">
<DocsTabsList>
<DocsTabsTrigger value="codex">Codex</DocsTabsTrigger>
<DocsTabsTrigger value="claude">Claude Code</DocsTabsTrigger>
<DocsTabsTrigger value="cursor">Cursor</DocsTabsTrigger>
<DocsTabsTrigger value="opencode">OpenCode</DocsTabsTrigger>
<DocsTabsTrigger value="vscode">VS Code</DocsTabsTrigger>
<DocsTabsTrigger value="devin">Devin</DocsTabsTrigger>
</DocsTabsList>
<DocsTabsContent value="codex">
```toml title="~/.codex/config.toml"
[mcp_servers.starwind_ui]
command = "npx"
args = ["-y", "@starwind-ui/mcp"]
enabled = true
```
</DocsTabsContent>
<DocsTabsContent value="claude">
```json title=".mcp.json"
{
  "mcpServers": {
    "starwind-ui": {
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"],
      "env": {}
    }
  }
}
```
</DocsTabsContent>
<DocsTabsContent value="cursor">
```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "starwind-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"],
      "env": {}
    }
  }
}
```
</DocsTabsContent>
<DocsTabsContent value="opencode">
```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "starwind-ui": {
      "type": "local",
      "command": ["npx", "-y", "@starwind-ui/mcp"],
      "enabled": true
    }
  }
}
```
</DocsTabsContent>
<DocsTabsContent value="vscode">
```json title=".vscode/mcp.json"
{
  "servers": {
    "starwind-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"]
    }
  }
}
```
</DocsTabsContent>
<DocsTabsContent value="devin">
```json title=".devin/mcp_config.json"
{
  "mcpServers": {
    "starwind-ui": {
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"]
    }
  }
}
```

This project file configures Devin Local, the default agent in new Devin Desktop tabs. You can
also create it with `devin mcp add -s project starwind-ui -- npx -y @starwind-ui/mcp`.
</DocsTabsContent>
</DocsTabs>

After you add the configuration, reload the MCP server when your client requires it. Use the
client's MCP status view or list command to confirm that Starwind UI connected.

## What You Can Do

With the MCP server, an assistant can:

- Prepare a validated Starwind UI v3 initialization command for an Astro or React project.
- Search styled components, Primitives, and Starwind Pro blocks.
- Generate validated install commands for the selected framework and project.
- Fetch exact component, Primitive, Runtime, migration, and framework documentation.
- Check a legacy Astro project and prepare a safe Starwind UI v3 migration command.

The server inspects local project context when available. It returns commands for the assistant to
review with you. It does not run those commands.

## Available Tools

| Tool | Use it for |
| --- | --- |
| `starwind_init` | Prepare a Starwind UI v3 initialization command. |
| `starwind_search` | Find styled components, Primitives, and Pro blocks. |
| `starwind_add` | Prepare validated install commands. |
| `starwind_docs` | Read current Starwind documentation. |
| `starwind_migrate` | Check and guide a legacy Astro migration. |

## Example Prompts

- "Find a React combobox and show me its documentation."
- "Add button, card, and dialog to this Astro project."
- "Show me the Primitive and Runtime API for Color Picker."
- "Check whether this project needs the Starwind UI v3 migration."
- "Find free Starwind Pro hero blocks."

Use [Starwind Skills](/docs/getting-started/skills/) with MCP when your assistant supports both.
Skills provide editing guidance. MCP supplies current Starwind data and commands.

## Troubleshooting

If the tools do not appear, restart or reload the server from the client's MCP controls. Confirm
that the client can run:

```bash
npx -y @starwind-ui/mcp
```

If your client still shows `search_starwind_pro_blocks`, stop the old MCP process and restart the
client. Current releases use `starwind_search` for components, Primitives, and Pro blocks.

## Client Documentation

- [Codex MCP docs](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
- [Claude Code MCP docs](https://code.claude.com/docs/en/mcp)
- [Cursor MCP docs](https://cursor.com/docs/mcp)
- [OpenCode MCP docs](https://opencode.ai/docs/mcp-servers/)
- [VS Code MCP docs](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
- [Devin Local MCP docs](https://docs.devin.ai/cli/extensibility/mcp/configuration)

---

Source: [https://starwind.dev/docs/getting-started/migration/](https://starwind.dev/docs/getting-started/migration/) · [Markdown](https://starwind.dev/docs/getting-started/migration.md)

# Migration Guide

Use `starwind migrate` when a project still has the old Astro copied-component setup. The command
migrates as much as it safely can in one guided run and leaves anything unresolved in config as
`source: "legacy"`.

```bash
starwind migrate
```

> **Info:** It is recommended to read [Migrating Astro Projects to Starwind UI v3](/blog/migrating-to-starwind-ui-v3/) before you
start. It covers the prerequisites and the application changes that require manual review after
the command finishes.

## What The Command Does

- Reads `starwind.config.json` and detects the legacy config shape.
- Inspects the public component directory, normally `src/components/starwind`.
- Offers to back up existing component folders to `src/components/starwind-legacy`.
- Creates a numbered backup such as `src/components/starwind-legacy-1` if the default backup path
already exists.
- Overwrites registered conflicts after a successful backup, because the previous folders are then
recoverable. If you decline the backup, it asks about bulk and individual conflict overwrites.
- Leaves unrelated custom folders alone.
- Installs the package requirements declared by the Runtime registry.
- Writes a v2 config with `framework: "astro"` as the Runtime output target.
- Applies registry-declared public rename codemods when you approve them.

## Public Import Paths

Migration keeps the public component path at `src/components/starwind` by default. Existing imports
such as this should remain the normal public shape after migration:

```astro
```

## Backup And Overwrite Prompts

The backup prompt protects your old component source before replacement. If you accept it, the CLI
copies the current Starwind component folder before writing Runtime-backed styled components.

After a successful backup, registered component conflicts are overwritten without another prompt.
If you decline the backup, the CLI first offers to overwrite all conflicts. Declining that bulk
overwrite opens a prompt for each conflicting component. Any component you keep remains in place
and is written to config with `source: "legacy"`.

When the registry declares a public component rename, migration can scan project source files and
offer to update matching component import paths and exported names. Component folders, backup
directories, generated output, dependencies, and `starwind.config.json` are excluded from that
codemod scan.

## Migration Report

The final report separates the important outcomes:

- `Migrated`: Runtime-backed styled components written successfully.
- `Skipped`: Conflicting component folders that were not overwritten.
- `Backed up`: the Starwind component directory copied into a legacy backup directory.
- `Custom`: folders in the Starwind directory that were not registry components.
- `Legacy`: unresolved entries that remain in config with `source: "legacy"`.
- `Updated project imports/usages`: registry-declared rename codemods that changed source files.
- `Skipped import/usage updates`: rename codemods that you declined.
- `No matching imports/usages found`: approved rename codemods that found nothing to change.

## After Migration

Use the normal Runtime CLI commands after migration:

```bash
starwind add button
starwind update button
starwind primitives add button
starwind docs button
```

---

Source: [https://starwind.dev/docs/getting-started/primitives/](https://starwind.dev/docs/getting-started/primitives/) · [Markdown](https://starwind.dev/docs/getting-started/primitives.md)

# Primitives

Primitives provide Runtime-backed behavior and anatomy without Starwind's styled wrapper. Most
projects should begin with a styled component and use a Primitive only when they need to own the
markup, styling, or adapter source at a lower layer.

## Choose a Layer

| Approach | Use it when |
| --- | --- |
| Styled component | You want ready-to-render Starwind UI with editable application source. |
| Primitive package | You want framework-native anatomy and behavior while keeping the adapter as a dependency. |
| Vendored Primitive source | You need to modify and own the framework adapter source in your project. |
| Runtime and raw HTML | You render your own DOM contract or are building a custom integration. |

The behavior-first reference for individual components remains in the
[Primitive API section](/docs/primitives/). Direct low-level initialization belongs in
[Runtime And Raw HTML](/docs/runtime/).

## Import Primitive Packages

`starwind init` installs the adapter for the project's primary framework, so initialized projects
usually need no additional package command. Install an adapter directly when the project was set up
manually or when you need the other framework package as well.

```bash
npm install @starwind-ui/astro
npm install @starwind-ui/react
```

Import only the package matching the file you are authoring. Primitive API pages show the available
parts, props, Runtime links, and framework-specific examples.

## Vendor Primitive Source

Vendoring copies compile-ready adapter source into the project. You own those files after they are
written, including any changes you make. The CLI tracks the installed Primitive versions so it can
plan later updates.

```bash
starwind primitives add button
starwind primitives update button
starwind primitives list
```

Use `update --dry-run`, `--diff`, or `--view` before accepting an update when you have modified
vendored files. The complete options belong in the [CLI primitives reference](/docs/getting-started/cli/#primitives).

## Framework Targeting

Without an override, Primitive commands use the primary framework from `starwind.config.json`.
Target Astro or React explicitly when a project contains both:

```bash
starwind primitives add button --framework react
starwind primitives list --framework all
```

The primary framework uses `primitiveDir`, which defaults to
`src/components/starwind-primitives`. Additional frameworks use `primitiveDirs.<framework>` and
default to a framework-specific directory such as `src/components/starwind-react-primitives`.

## Custom Destinations

Use `--to <dir>` when vendored source should live somewhere other than the configured destination.
The CLI records the selected location for future operations.

```bash
starwind primitives add button --to src/primitives
starwind primitives add button --framework react --to src/react-primitives
```

Keep imports pointed at the vendored directory you selected. When you only need package imports,
do not vendor the same Primitive unless you intentionally want to maintain a local fork.

## Ownership and Updates

- Package imports receive adapter changes through normal dependency updates.
- Vendored source changes only when you run a Primitive update command.
- Review vendored updates like application code because they may overwrite local modifications.
- Runtime internals remain package dependencies; Primitive vendoring does not copy Runtime source.

See the [CLI reference](/docs/getting-started/cli/) for every command and option, or open the
[Primitive API reference](/docs/primitives/) to choose a component.

---

Source: [https://starwind.dev/docs/getting-started/skills/](https://starwind.dev/docs/getting-started/skills/) · [Markdown](https://starwind.dev/docs/getting-started/skills.md)

# Skills

Starwind Skills give AI assistants project-aware guidance for Starwind UI v3. Compatible agents can
select the right Starwind layer, follow Astro or React conventions, migrate older projects, update
components safely, customize Tailwind CSS v4 themes, and work with Starwind Pro blocks.

The public skills live in [starwind-ui/skills](https://github.com/starwind-ui/skills).

For example, you can ask your AI assistant to:

- "Build an accessible Astro account settings form with validation, notification switches, and a
busy Save button."
- "Create a React edit-profile dialog with an avatar and searchable Starwind Combobox."
- "Rebrand this project with semantic colors for light and dark modes while preserving the existing
theme."
- "Adapt this installed Pro hero block for my product while preserving its responsive, dark-mode,
and motion behavior."

## Install

```bash
npx skills@latest add starwind-ui/skills
```

The installer discovers the `starwind-ui` and `starwind-pro` skills from GitHub. It then lets you
select the target agents and installation scope. Learn more about skills at
[skills.sh](https://skills.sh).

## Update

Update both installed skills when Starwind publishes new guidance:

```bash
npx skills@latest update starwind-ui starwind-pro
```

## Choose a Layer

| Layer | Choose it when |
| --- | --- |
| Styled component | You want the default, complete component installed with `starwind add`. |
| Primitive | You need lower-level anatomy from a package or vendored source. |
| Runtime | You need raw DOM behavior or are building a custom framework adapter. |

## What's Included

### Starwind UI

The `starwind-ui` skill applies to Starwind UI v3 projects that use Astro or React. It covers styled
components, Primitive packages or vendored Primitive source, direct Runtime integrations, Tailwind
CSS v4, `starwind.config.json`, migrations, updates, theme tokens, dark mode, and composition.

It guides agents to:

- Prefer `npx starwind@latest init`, `npx starwind@latest add`, and other documented Starwind CLI
commands.
- Read current Starwind docs through docs URLs, Markdown pages, `llms-full.txt`, the CLI, or MCP when
available.
- Compose existing Starwind components instead of injecting raw copied HTML.
- Preview component updates and preserve project customizations.

### Starwind Pro

The `starwind-pro` skill applies when an agent is discovering, installing, or adapting Starwind Pro
blocks.

It guides agents to:

- Distinguish free blocks from premium blocks that require Starwind Pro access.
- Check V3 access and `starwind.config.json` before installing premium blocks.
- Use the exact block install command returned by current search results.
- Preserve responsive behavior, accessibility, and theme integration while adapting blocks.

## How It Works

1. The skill activates when an agent is working in a Starwind UI or Starwind Pro context.
2. The agent reads the local project shape, including `package.json`, framework config,
`starwind.config.json`, installed components, theme CSS, and import aliases.
3. The agent uses current Starwind context from docs, Markdown pages, `llms-full.txt`, the CLI, or the
MCP server before generating code.
4. The agent follows current framework and component APIs. Astro uses `class` and `for`. React uses
`className` and `htmlFor`. The agent can install `Combobox` for searchable selection and preview
updates before it changes customized files.

## Skills And MCP

Skills and MCP solve different parts of the workflow:

| Surface | Use it for |
| --- | --- |
| Skills | Persistent agent behavior, Starwind-specific rules, and project editing guidance. |
| MCP Server | Current lookup data and validated commands for components, docs, migrations, and Pro blocks. |
| Markdown docs | Focused page-level context by appending `.md` to the docs path. |
| `llms.txt` | Compact discovery and links to current AI surfaces. |
| `ai-manifest.json` | Structured inventory, framework availability, Skills, and MCP metadata. |
| `llms-full.txt` | Full static docs context when an agent cannot call MCP tools. |

Use both Skills and [MCP](/docs/getting-started/mcp/) when your agent supports them. Skills teach the
agent how to edit a project. MCP returns current Starwind data and commands for the agent to review.

---

Source: [https://starwind.dev/docs/getting-started/theming/](https://starwind.dev/docs/getting-started/theming/) · [Markdown](https://starwind.dev/docs/getting-started/theming.md)

# Theming

CSS variables are used for styling the components and creating Tailwind CSS utility classes.

## Convention

We use a simple `background` and `foreground` convention for colors. The `background` variable is used for the background color of the components, and the `foreground` variable is used for the color of the text. Note that the `background` suffix is often omitted.

> **Info:** The css variables are extremely similar to shadcn, making it easy to convert to use starwind, or to use both in your project.

## CSS Variables

Below are all the variables in use, with comments for each variable describing what it does. By default, all colors used are [default tailwind colors](https://tailwindcss.com/docs/colors#default-color-palette-reference).

```css title="src/styles/starwind.css"
/* allows you to use "dark:" variant in your html and have it match the .dark css variables */
@custom-variant dark (&:where(.dark, .dark *));

/* ... */

:root {
  /* default color of <body> background and text */
  --background: var(--color-neutral-50);
  --foreground: var(--color-neutral-950);

/* Background and text color for <Card> */
  --card: var(--color-neutral-50);
  --card-foreground: var(--color-neutral-950);

/* Colors for popovers like <SelectContent> and <TooltipContent> */
  --popover: var(--color-neutral-50);
  --popover-foreground: var(--color-neutral-950);

/* Primary colors for <Button>, etc. when variant="primary" */
  --primary: var(--color-blue-700);
  --primary-foreground: var(--color-neutral-50);

/* Primary color that is accessible for text on the background color */
  --primary-accent: var(--color-blue-800);

/* Secondary colors for <Button>, etc. when variant="secondary" */
  --secondary: var(--color-neutral-200);
  --secondary-foreground: var(--color-neutral-950);

/* Secondary color that is accessible for text on the background color */
  --secondary-accent: var(--color-neutral-950);

/* Muted colors use for <TabsList>, <Avatar>, etc. */
  --muted: var(--color-neutral-100);
  --muted-foreground: var(--color-neutral-600);

/* Accents like hover effects on <SelectItem> */
  --accent: var(--color-neutral-200);
  --accent-foreground: var(--color-neutral-900);

/* Various component colors for variant="info" */
  --info: var(--color-sky-300);
  --info-foreground: var(--color-sky-950);

/* Various component colors for variant="success" */
  --success: var(--color-green-300);
  --success-foreground: var(--color-green-950);

/* Various component colors for variant="warning" */
  --warning: var(--color-amber-300);
  --warning-foreground: var(--color-amber-950);

/* Various component colors for variant="error" */
  --error: var(--color-red-700);
  --error-foreground: var(--color-neutral-50);

/* Default border color */
  --border: var(--color-neutral-200);

/* Border colors for inputs like <Input>, <Textarea>, <SelectTrigger>  */
  --input: var(--color-neutral-200);

/* Used for focus outline */
  --outline: var(--color-blue-600);

/* Border radius for various elements */
  --radius: 0.5rem;
}

/* overriding above variables when a parent has the class "dark" */
.dark {
  --background: var(--color-neutral-950);
  --foreground: var(--color-neutral-50);
  /* etc... */
}
/* ... */
```

## Adding new colors

You can add additional color themes by creating a new Tailwind CSS `variant`, and adding it with new variable assignments to the `@theme`.

```css title="src/styles/starwind.css" ins={5,20-46}
/* allows you to use "dark:" variant in your html and have it match the `.dark` css variables */
@custom-variant dark (&:where(.dark, .dark *));

/* allows you to use "newcolor:" variant in your html and have it match the `.my-new-color` css variables */
@custom-variant newcolor (&:where(.my-new-color, .my-new-color *));

/* ... */

:root {
  /* base variables (light mode) */
}

.dark {
  /* dark mode variables */
}

/* overriding above variables when a parent has the class "my-new-color" */
/* edit these variables to whatever you want them to be in that context */
.my-new-color {
  --background: var(--color-neutral-950);
  --foreground: var(--color-neutral-50);
  --card: var(--color-neutral-950);
  --card-foreground: var(--color-neutral-50);
  --popover: var(--color-neutral-950);
  --popover-foreground: var(--color-neutral-50);
  --primary: var(--color-blue-700);
  --primary-foreground: var(--color-neutral-50);
  --secondary: var(--color-fuchsia-300);
  --secondary-foreground: var(--color-neutral-950);
  --muted: var(--color-neutral-900);
  --muted-foreground: var(--color-neutral-400);
  --accent: var(--color-neutral-900);
  --accent-foreground: var(--color-neutral-100);
  --info: var(--color-sky-300);
  --info-foreground: var(--color-sky-950);
  --success: var(--color-green-300);
  --success-foreground: var(--color-green-950);
  --warning: var(--color-amber-300);
  --warning-foreground: var(--color-amber-950);
  --error: var(--color-red-800);
  --error-foreground: var(--color-neutral-50);
  --border: var(--color-neutral-800);
  --input: var(--color-neutral-800);
  --outline: var(--color-blue-600);
}
/* ... */
```

## Adding new theme variables

Following standard Tailwind CSS v4 variable naming conventions, you can add new Tailwind CSS variables to the `@theme` block.

> **Tip:** You should add this to the `@theme inline` block specifically, so you can reference your variables defined for `:root` and `.dark`.

```scss title="src/styles/starwind.css" ins={3,13,18}
@theme inline {
  /* will allow you to use `border-canvas`, `bg-canvas`, etc. */
  --color-canvas: var(--acme-canvas-color);

/* standard Starwind UI variables */
	--color-background: var(--background);
	--color-foreground: var(--foreground);
  /* etc... */
}

:root {
  --acme-canvas-color: oklch(0.967 0.003 264.542);
  /* etc... */
}

.dark {
  --acme-canvas-color: oklch(0.21 0.034 264.665);
  /* etc... */
}
```

## Relevant Tailwind docs

- [Dark mode](https://tailwindcss.com/docs/dark-mode)
- [Custom variants](https://tailwindcss.com/docs/functions-and-directives#custom-variant-directive)
- [@theme inline keyword](https://tailwindcss.com/docs/colors#referencing-other-variables)
- [Theme variables](https://tailwindcss.com/docs/theme)

---

Source: [https://starwind.dev/docs/primitives/](https://starwind.dev/docs/primitives/) · [Markdown](https://starwind.dev/docs/primitives.md)

# Runtime Primitives

Starwind currently exposes 36 Runtime-backed primitives for Astro and React. They use the same
use-case groups as the styled component overview, making it easy to move between the styled and
behavior-first layers.

## Form & Input

Collect and validate user input.

### Fields and Validation

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Field](/docs/primitives/field/) | `createField` | 7 | 1 |
| [Fieldset](/docs/primitives/fieldset/) | `createFieldset` | 2 | 1 |
| [Form](/docs/primitives/form/) | `createForm` | 2 | 1 |

### Text, File, and Value Inputs

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Color Picker](/docs/primitives/color-picker/) | `createColorPicker` | 23 | 1 |
| [Dropzone](/docs/primitives/dropzone/) | `createDropzone` | 5 | 1 |
| [Input](/docs/primitives/input/) | `createInput` | 1 | 1 |
| [Input OTP](/docs/primitives/input-otp/) | `createInputOtp` | 7 | 1 |
| [Slider](/docs/primitives/slider/) | `createSlider` | 7 | 1 |

### Selection Controls

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Checkbox](/docs/primitives/checkbox/) | `createCheckbox` | 4 | 1 |
| [Checkbox Group](/docs/primitives/checkbox-group/) | `createCheckboxGroup` | 1 | 1 |
| [Combobox](/docs/primitives/combobox/) | `createCombobox` | 20 | 1 |
| [Radio](/docs/primitives/radio/) | `createRadio` | 3 | 1 |
| [Radio Group](/docs/primitives/radio-group/) | `createRadioGroup` | 1 | 1 |
| [Select](/docs/primitives/select/) | `createSelect` | 18 | 1 |
| [Switch](/docs/primitives/switch/) | `createSwitch` | 4 | 1 |

### Actions and Toggles

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Button](/docs/primitives/button/) | `createButton` | 1 | 1 |
| [Toggle](/docs/primitives/toggle/) | `createToggle` | 1 | 2 |
| [Toggle Group](/docs/primitives/toggle-group/) | `createToggleGroup` | 1 | 1 |

## Navigation

Move users through pages, sections, and app states.

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Menu](/docs/primitives/menu/) | `createMenu` | 18 | 1 |
| [Navigation Menu](/docs/primitives/navigation-menu/) | `createNavigationMenu` | 12 | 1 |
| [Sidebar](/docs/primitives/sidebar/) | `createSidebarController` | 5 | 1 |
| [Tabs](/docs/primitives/tabs/) | `createTabs` | 5 | 1 |

## Overlay & Disclosure

Reveal additional information or contextual actions.

### Inline Disclosure

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Accordion](/docs/primitives/accordion/) | `createAccordion` | 5 | 1 |
| [Collapsible](/docs/primitives/collapsible/) | `createCollapsible` | 3 | 1 |

### Dialogs and Drawers

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Alert Dialog](/docs/primitives/alert-dialog/) | `createAlertDialog` | 9 | 1 |
| [Dialog](/docs/primitives/dialog/) | `createDialog` | 7 | 1 |
| [Drawer](/docs/primitives/drawer/) | `createDrawer` | 9 | 1 |

### Floating and Contextual Overlays

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Context Menu](/docs/primitives/context-menu/) | `createContextMenu` | 19 | 1 |
| [Popover](/docs/primitives/popover/) | `createPopover` | 11 | 1 |
| [Preview Card](/docs/primitives/preview-card/) | `createPreviewCard` | 8 | 1 |
| [Tooltip](/docs/primitives/tooltip/) | `createTooltip` | 6 | 1 |

## Feedback & Status

Communicate progress, outcomes, and loading states.

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Progress](/docs/primitives/progress/) | `createProgress` | 5 | 1 |
| [Toast](/docs/primitives/toast/) | `createToastManager` | 9 | 1 |

## Layout & Structure

Build consistent spatial structure and content organization.

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Scroll Area](/docs/primitives/scroll-area/) | `createScrollArea` | 6 | 1 |

## Content & Media

Present media, rich text, and supporting UI metadata.

| Primitive | Runtime factory | Parts | Styled components |
| --- | --- | ---: | ---: |
| [Avatar](/docs/primitives/avatar/) | `createAvatar` | 3 | 1 |
| [Carousel](/docs/primitives/carousel/) | `createCarousel` | 6 | 1 |

## Installation

`starwind init` installs the Primitive adapter for your project's primary framework. If you are
configuring Starwind manually, install the package that matches the files you are authoring:

```bash
npm install @starwind-ui/astro
# or
npm install @starwind-ui/react
```

You can also copy Primitive adapter source into your project with `starwind primitives add`. See
the [Getting Started Primitives guide](/docs/getting-started/primitives/) for the package, vendored
source, and Runtime/raw HTML tradeoffs.

## Import Pattern

Import each Primitive from its framework package and component subpath. The individual reference
pages show the available parts and complete examples for both frameworks.

**Astro**

```ts
import { Accordion } from "@starwind-ui/astro/accordion";
```

**React**

```ts
import { Accordion } from "@starwind-ui/react/accordion";
```

When you vendor Primitive source, import from the configured `primitiveDir` or
`primitiveDirs.<framework>` destination instead.

## Styling and Composition

Primitives provide behavior and framework-native anatomy without Starwind's styled wrapper. You
own the rendered markup and styling while the adapter coordinates the underlying Runtime contract.
Start with a [styled component](/docs/components/) when you want ready-to-render UI, or continue to
the [Runtime reference](/docs/runtime/) when you need to initialize behavior against raw HTML.

---

Source: [https://starwind.dev/docs/primitives/accordion/](https://starwind.dev/docs/primitives/accordion/) · [Markdown](https://starwind.dev/docs/primitives/accordion.md)

# Accordion Primitive

Accordion is a Starwind Runtime primitive in the controlled-value-group contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Accordion anatomy with the Runtime wiring included.
```astro
---
import { Accordion } from "@starwind-ui/astro/accordion";
---

<Accordion.Root>
  <Accordion.Item value="details">
    <Accordion.Header>
      <Accordion.Trigger>Toggle details</Accordion.Trigger>
    </Accordion.Header>
    <Accordion.Panel>Accordion panel content</Accordion.Panel>
  </Accordion.Item>
</Accordion.Root>
```

### React
Use the React primitive adapter when Accordion state participates in React rendering.
```tsx
import { Accordion } from "@starwind-ui/react/accordion";

export function Example() {
  return (
    <Accordion.Root>
      <Accordion.Item value="details">
        <Accordion.Header>
          <Accordion.Trigger>Toggle details</Accordion.Trigger>
        </Accordion.Header>
        <Accordion.Panel>Accordion panel content</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  );
}
```

### HTML
Render the Accordion data-sw-* contract yourself, then initialize createAccordion.
```html
<div data-sw-accordion>
  <div data-sw-accordion-item data-value="details">
    <h3 data-sw-accordion-header>
      <button data-sw-accordion-trigger type="button">Toggle details</button>
    </h3>
    <div data-sw-accordion-content role="region" hidden>Accordion panel content</div>
  </div>
</div>

const root = document.querySelector("[data-sw-accordion]");
  if (root) {
    createAccordion(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Accordion Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-accordion` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `AccordionValue` | - | control | Controls the current Accordion value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `AccordionValue` | - | control | Sets the initial Accordion value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| type | `"single" \| "multiple"` | "single" | option | Sets the native type for the Root part. | - |
| collapsible | `boolean` | true | option | Allows all Accordion items to be collapsed. | - |
| onValueChange | `(value: AccordionValue, details: AccordionValueChangeDetails) => void` | - | callback | Runs when the Accordion value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-accordion` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-type` | prop | - | Reflects the type prop on the Root part. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-collapsible` | prop | - | Reflects the collapsible prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `AccordionValue` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Accordion value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `AccordionValue` | AccordionValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Accordion. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Accordion value from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-accordion`, `data-type`, `data-default-value`, `data-collapsible`, `data-state` | The root needs type, default value, collapsibility, and initial closed state before controller hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |

### Item
An interactive item inside the Accordion collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-accordion-item` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `string` | - | option | Controls the current Accordion value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| disabled | `boolean` | false | option | Disables the Item part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-accordion-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Item part. |
| `data-state` | state | - | Reflects the current state on the Item part. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-accordion-item`, `data-value`, `data-disabled`, `data-state` | Items need stable value, disabled, and closed-state markers before trigger and panel ids are linked. |

### Header
The header container for a Accordion item.
| Fact | Value |
| --- | --- |
| Default element | `h3` |
| Discovery hook | `data-sw-accordion-header` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-accordion-header` | runtime | - | Marks the Header part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| header | Yes |

### Trigger
The control that opens, closes, or targets the Accordion content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-accordion-trigger` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-accordion-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-accordion-trigger`, `type`, `aria-expanded`, `data-state` | Triggers need button semantics and collapsed affordances before the runtime wires aria-controls. |

### Panel
The content panel controlled by Accordion.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-accordion-content` |
| Role | `region` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-accordion-content` | runtime | - | Marks the Panel part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Panel part. |
#### Refs
| Part | Public |
| --- | --- |
| panel | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-accordion-content`, `data-state`, `hidden` | Panels start hidden and closed; the runtime controls height variables and close-animation visibility. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createAccordion`](/docs/runtime/#create-accordion) |
| Import | `@starwind-ui/runtime/accordion` |
| Root part | root |
| Option props | type, defaultValue, collapsible, value |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Accordion](/docs/components/accordion/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/accordion` | `createAccordion` |
| Astro Primitive | `@starwind-ui/astro/accordion` | `Accordion`, `AccordionRoot`, `AccordionItem`, `AccordionHeader`, `AccordionTrigger`, `AccordionPanel` |
| React Primitive | `@starwind-ui/react/accordion` | `Accordion`, `AccordionRoot`, `AccordionItem`, `AccordionHeader`, `AccordionTrigger`, `AccordionPanel` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Accordion` |
| runtime-factory | `createAccordion` |
| part | `Accordion.Root` |
| part | `Accordion.Item` |
| part | `Accordion.Header` |
| part | `Accordion.Trigger` |
| part | `Accordion.Panel` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.3
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.2
- Made value-change proposals synchronously cancelable before uncontrolled state commits.
### v0.1.1
- Made single-value accordions collapsible by default while preserving the option to require one item to remain open.
### v0.1.0
- Introduced Runtime-managed single and multiple disclosure state, keyboard navigation, and panel presence.

---

Source: [https://starwind.dev/docs/primitives/alert-dialog/](https://starwind.dev/docs/primitives/alert-dialog/) · [Markdown](https://starwind.dev/docs/primitives/alert-dialog.md)

# Alert Dialog Primitive

Alert Dialog is a Starwind Runtime primitive in the dialog-native-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render AlertDialog anatomy with the Runtime wiring included.
```astro
---
import { AlertDialog } from "@starwind-ui/astro/alert-dialog";
---

<AlertDialog.Root>
  <AlertDialog.Trigger>Delete item</AlertDialog.Trigger>
  <AlertDialog.Backdrop />
  <AlertDialog.Viewport>
    <AlertDialog.Popup>
      <AlertDialog.Title>Delete item?</AlertDialog.Title>
      <AlertDialog.Description>This action cannot be undone.</AlertDialog.Description>
      <AlertDialog.Close>Cancel</AlertDialog.Close>
    </AlertDialog.Popup>
  </AlertDialog.Viewport>
</AlertDialog.Root>
```

### React
Use the React primitive adapter when AlertDialog state participates in React rendering.
```tsx
import { AlertDialog } from "@starwind-ui/react/alert-dialog";

export function Example() {
  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger>Delete item</AlertDialog.Trigger>
      <AlertDialog.Backdrop />
      <AlertDialog.Viewport>
        <AlertDialog.Popup>
          <AlertDialog.Title>Delete item?</AlertDialog.Title>
          <AlertDialog.Description>This action cannot be undone.</AlertDialog.Description>
          <AlertDialog.Close>Cancel</AlertDialog.Close>
        </AlertDialog.Popup>
      </AlertDialog.Viewport>
    </AlertDialog.Root>
  );
}
```

### HTML
Render the AlertDialog data-sw-* contract yourself, then initialize createAlertDialog.
```html
<div data-sw-alert-dialog>
  <button data-sw-alert-dialog-trigger type="button" aria-haspopup="dialog">Delete item</button>
  <div data-sw-alert-dialog-backdrop hidden></div>
  <div data-sw-alert-dialog-viewport>
    <dialog data-sw-alert-dialog-popup role="alertdialog">
      <h2 data-sw-alert-dialog-title>Delete item?</h2>
      <p data-sw-alert-dialog-description>This action cannot be undone.</p>
      <button data-sw-alert-dialog-close type="button">Cancel</button>
    </dialog>
  </div>
</div>

const root = document.querySelector("[data-sw-alert-dialog]");
  if (root) {
    createAlertDialog(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Alert Dialog Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-alert-dialog` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Alert Dialog is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Alert Dialog starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| closeOnEscape | `boolean` | true | option | Closes Alert Dialog when Escape is pressed. | - |
| closeOnOutsideInteract | `boolean` | false | option | Closes Alert Dialog when the user interacts outside it. | - |
| modal | `boolean` | true | option | Makes Alert Dialog behave as a modal overlay. | - |
| onCloseComplete | `(open: boolean, details: AlertDialogCloseCompleteDetails) => void` | - | callback | Runs after Alert Dialog has finished closing. | - |
| onOpenChange | `(open: boolean, details: AlertDialogOpenChangeDetails) => void` | - | callback | Runs when Alert Dialog opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-alert-dialog` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-close-on-escape` | prop | - | Reflects the close on escape prop on the Root part. |
| `data-close-on-outside-interact` | prop | - | Reflects the close on outside interact prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Alert Dialog is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| closeComplete | onCloseComplete | starwind:close-complete | open: `boolean` | AlertDialogCloseCompleteDetails | after-state-commit | No | Fires after Alert Dialog has finished closing. | - |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | AlertDialogOpenChangeDetails | before-state-commit | Yes | Fires when Alert Dialog opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Alert Dialog from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-alert-dialog`, `data-default-open`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-modal`, `data-state` | The alert dialog root needs default-open, dismissal, modality, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Alert Dialog content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-alert-dialog-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| targetId | `string` | - | attribute | Targets a specific root element by id. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-alert-dialog-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-sw-alert-dialog-target-id` | prop | - | Reflects the sw alert dialog target id prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-alert-dialog-trigger`, `type`, `aria-haspopup`, `data-sw-alert-dialog-target-id`, `data-state` | Triggers need button semantics, dialog affordances, and initial closed state before activation listeners attach. |

### Portal
Moves Alert Dialog overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-alert-dialog-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-alert-dialog-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Backdrop
The backdrop shown behind the Alert Dialog overlay.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-alert-dialog-backdrop` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-alert-dialog-backdrop` | runtime | - | Marks the Backdrop part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Backdrop part. |
#### Refs
| Part | Public |
| --- | --- |
| backdrop | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-alert-dialog-backdrop`, `data-state`, `hidden` | The backdrop starts hidden and receives runtime-owned open/close visibility. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Viewport
The visible viewport for Alert Dialog content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-alert-dialog-viewport` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-alert-dialog-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |

### Popup
The floating content container for Alert Dialog.
| Fact | Value |
| --- | --- |
| Default element | `dialog` |
| Discovery hook | `data-sw-alert-dialog-popup` |
| Role | `alertdialog` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-alert-dialog-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-alert-dialog-popup`, `role`, `data-state` | The native popup starts closed with alertdialog semantics before runtime normalization maps it onto the Dialog controller. |

### Title
The accessible title for Alert Dialog.
| Fact | Value |
| --- | --- |
| Default element | `h2` |
| Discovery hook | `data-sw-alert-dialog-title` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-alert-dialog-title` | runtime | - | Marks the Title part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| title | Yes |

### Description
Supporting description text for Alert Dialog.
| Fact | Value |
| --- | --- |
| Default element | `p` |
| Discovery hook | `data-sw-alert-dialog-description` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-alert-dialog-description` | runtime | - | Marks the Description part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| description | Yes |

### Close
A control that closes Alert Dialog.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-alert-dialog-close` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-alert-dialog-close` | runtime | - | Marks the Close part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| close | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-alert-dialog-close`, `type` | Action/cancel controls need button semantics before runtime listeners attach. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createAlertDialog`](/docs/runtime/#create-alert-dialog) |
| Import | `@starwind-ui/runtime/alert-dialog` |
| Root part | root |
| Option props | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open |
| Option lifecycles | closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultOpen: constructor-only, modal: constructor-only, onCloseComplete: constructor-only, onOpenChange: constructor-only, open: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Alert Dialog](/docs/components/alert-dialog/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/alert-dialog` | `createAlertDialog` |
| Astro Primitive | `@starwind-ui/astro/alert-dialog` | `AlertDialog`, `AlertDialogRoot`, `AlertDialogTrigger`, `AlertDialogPortal`, `AlertDialogBackdrop`, `AlertDialogViewport`, `AlertDialogPopup`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogClose` |
| React Primitive | `@starwind-ui/react/alert-dialog` | `AlertDialog`, `AlertDialogRoot`, `AlertDialogTrigger`, `AlertDialogPortal`, `AlertDialogBackdrop`, `AlertDialogViewport`, `AlertDialogPopup`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogClose` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `AlertDialog` |
| runtime-factory | `createAlertDialog` |
| part | `AlertDialog.Root` |
| part | `AlertDialog.Trigger` |
| part | `AlertDialog.Portal` |
| part | `AlertDialog.Backdrop` |
| part | `AlertDialog.Viewport` |
| part | `AlertDialog.Popup` |
| part | `AlertDialog.Title` |
| part | `AlertDialog.Description` |
| part | `AlertDialog.Close` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced modal confirmation state with focus management, dismissal rules, and accessible alert-dialog semantics.

---

Source: [https://starwind.dev/docs/primitives/avatar/](https://starwind.dev/docs/primitives/avatar/) · [Markdown](https://starwind.dev/docs/primitives/avatar.md)

# Avatar Primitive

Avatar is a Starwind Runtime primitive in the static-semantic contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Avatar anatomy with the Runtime wiring included.
```astro
---
import { Avatar } from "@starwind-ui/astro/avatar";
---

<Avatar.Root>
  <Avatar.Image alt="Starwind UI" src="/avatar.png" />
  <Avatar.Fallback>SW</Avatar.Fallback>
</Avatar.Root>
```

### React
Use the React primitive adapter when Avatar state participates in React rendering.
```tsx
import { Avatar } from "@starwind-ui/react/avatar";

export function Example() {
  return (
    <Avatar.Root>
      <Avatar.Image alt="Starwind UI" src="/avatar.png" />
      <Avatar.Fallback>SW</Avatar.Fallback>
    </Avatar.Root>
  );
}
```

### HTML
Render the Avatar data-sw-* contract yourself, then initialize createAvatar.
```html
<span data-sw-avatar>
  <img data-sw-avatar-image style="visibility: hidden" alt="Starwind UI" src="/avatar.png" />
  <span data-sw-avatar-fallback hidden>SW</span>
</span>

const root = document.querySelector("[data-sw-avatar]");
  if (root) {
    createAvatar(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Avatar Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-avatar` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-avatar` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-image-loading-status` | state | - | Reflects the image loading status state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| imageLoadingStatus | `AvatarImageLoadingStatus` | - | - | `data-image-loading-status` | `getImageLoadingStatus` | `setImageLoadingStatus` | Tracks whether the Avatar image is loading, loaded, or failed. | **React:** The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.<br>**Astro:** listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.<br>**Runtime / HTML:** Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| loadingStatusChange | onLoadingStatusChange | starwind:loading-status-change | status: `AvatarImageLoadingStatus` | AvatarLoadingStatusChangeDetails | after-state-commit | No | Fires when the image loading status changes for Avatar. | - |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-avatar`, `data-image-loading-status` | The root needs an initial loading-status marker so image and fallback state can style before the controller attaches. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |

### Image
The image element managed by Avatar.
| Fact | Value |
| --- | --- |
| Default element | `img` |
| Discovery hook | `data-sw-avatar-image` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| alt | `string` | - | attribute | Provides accessible alternative text for the image. | - |
| image | `ImageMetadata` | - | rendering | Provides image loading state to the avatar image part. | - |
| src | `string` | - | attribute | Sets the image source. | - |
| onLoadingStatusChange | `(status: AvatarImageLoadingStatus, details: AvatarLoadingStatusChangeDetails) => void` | - | callback | Runs when on loading status change changes for Avatar. | **React:** The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.<br>**Astro:** listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.<br>**Runtime / HTML:** Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-avatar-image` | runtime | - | Marks the Image part so Starwind Runtime can find it. |
| `data-image-loading-status` | state | - | Reflects the image loading status state on the Image part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| imageLoadingStatus | `AvatarImageLoadingStatus` | - | - | `data-image-loading-status` | `getImageLoadingStatus` | `setImageLoadingStatus` | Tracks whether the Avatar image is loading, loaded, or failed. | **React:** The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.<br>**Astro:** listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.<br>**Runtime / HTML:** Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates. |
#### Refs
| Part | Public |
| --- | --- |
| image | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-avatar-image`, `data-image-loading-status` | Images start visibility-hidden so they retain a layout box and remain eligible for native lazy loading until the Runtime confirms they loaded. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |

### Fallback
Fallback content shown when Avatar cannot load.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-avatar-fallback` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| delay | `number` | - | option | Sets how long to wait before showing fallback content. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-avatar-fallback` | runtime | - | Marks the Fallback part so Starwind Runtime can find it. |
| `data-delay` | prop | - | Reflects the delay prop on the Fallback part. |
| `data-image-loading-status` | state | - | Reflects the image loading status state on the Fallback part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| imageLoadingStatus | `AvatarImageLoadingStatus` | - | - | `data-image-loading-status` | `getImageLoadingStatus` | `setImageLoadingStatus` | Tracks whether the Avatar image is loading, loaded, or failed. | **React:** The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.<br>**Astro:** listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.<br>**Runtime / HTML:** Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates. |
#### Refs
| Part | Public |
| --- | --- |
| fallback | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-avatar-fallback`, `data-delay`, `data-image-loading-status` | Fallbacks carry optional delay metadata and may start hidden while the timer runs. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createAvatar`](/docs/runtime/#create-avatar) |
| Import | `@starwind-ui/runtime/avatar` |
| Root part | root |
| Option props | - |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Avatar](/docs/components/avatar/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/avatar` | `createAvatar` |
| Astro Primitive | `@starwind-ui/astro/avatar` | `Avatar`, `AvatarRoot`, `AvatarImage`, `AvatarFallback` |
| React Primitive | `@starwind-ui/react/avatar` | `Avatar`, `AvatarRoot`, `AvatarImage`, `AvatarFallback` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Avatar` |
| runtime-factory | `createAvatar` |
| part | `Avatar.Root` |
| part | `Avatar.Image` |
| part | `Avatar.Fallback` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.1
- Kept images eligible for native lazy loading while the Runtime conceals their loading and error states, including Astro images rendered from imported assets.
### v0.1.0
- Introduced image loading state, delayed fallback behavior, and accessible image status coordination.

---

Source: [https://starwind.dev/docs/primitives/button/](https://starwind.dev/docs/primitives/button/) · [Markdown](https://starwind.dev/docs/primitives/button.md)

# Button Primitive

Button uses native button semantics by default and adds Runtime behavior only for focusable-disabled state.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Button anatomy with the Runtime wiring included.
```astro
---
import { Button } from "@starwind-ui/astro/button";
---

<Button.Root type="button" focusableWhenDisabled={true}>Button</Button.Root>
```

### React
Use the React primitive adapter when Button state participates in React rendering.
```tsx
import { Button } from "@starwind-ui/react/button";

export function Example() {
  return (
    <Button.Root type="button" focusableWhenDisabled={true}>Button</Button.Root>
  );
}
```

### HTML
Render the Button data-sw-* contract yourself, then initialize createButton.
```html
<button data-sw-button type="button" data-focusable-when-disabled="">Button</button>

const root = document.querySelector("[data-sw-button]");
  if (root instanceof HTMLButtonElement) {
    const instance = createButton(root);
    root.addEventListener("click", () => instance.setDisabled(true), { once: true });
  }
</script>
```
## API Reference
### Root
The native button. It owns a Runtime instance only when focusableWhenDisabled opts into mutable focusable-disabled behavior.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-button` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the button natively unless focusableWhenDisabled keeps it focusable through Runtime. | - |
| focusableWhenDisabled | `boolean` | false | option | Opts the native button into Runtime so disabled state can suppress activation without removing focusability. | - |
| type | `button \| submit \| reset` | - | attribute | Sets the native button type; adapters default an omitted value to button. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-button` | runtime | - | Runtime discovery hook for an opted-in native button. |
| `data-focusable-when-disabled` | prop | - | Opts the native button into focusable-disabled Runtime behavior. |
| `data-disabled` | prop | - | Present while an opted-in button is disabled through Runtime. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setDisabled` | prop: disabled | - | No | Updates the opted-in button between enabled and focusable-disabled state without replacing it. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-button`, `data-focusable-when-disabled`, `type`, `data-disabled`, `aria-disabled` | Native button markup owns ordinary behavior; the focusable-disabled attribute conditionally opts the root into Runtime. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createButton`](/docs/runtime/#create-button) |
| Import | `@starwind-ui/runtime/button` |
| Root part | root |
| Option props | disabled |
| Option lifecycles | disabled: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Button](/docs/components/button/) | Mixed Conditional |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/button` | `createButton` |
| Astro Primitive | `@starwind-ui/astro/button` | `Button`, `ButtonRoot` |
| React Primitive | `@starwind-ui/react/button` | `Button`, `ButtonRoot` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Button` |
| runtime-factory | `createButton` |
| part | `Button.Root` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.1
- Limited focusable-disabled behavior to opted-in native buttons and synchronized mutable disabled state across Astro and React.
### v0.1.0
- Introduced Runtime-owned disabled interaction behavior while retaining native button and link semantics.

---

Source: [https://starwind.dev/docs/primitives/carousel/](https://starwind.dev/docs/primitives/carousel/) · [Markdown](https://starwind.dev/docs/primitives/carousel.md)

# Carousel Primitive

Carousel is a Starwind Runtime primitive in the viewport-measurement contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Carousel anatomy with the Runtime wiring included.
```astro
---
import { Carousel } from "@starwind-ui/astro/carousel";
---

<Carousel.Root>
  <Carousel.Viewport>
    <Carousel.Container>
      <Carousel.Item>Slide 1</Carousel.Item>
    </Carousel.Container>
  </Carousel.Viewport>
  <Carousel.Previous>Previous</Carousel.Previous>
  <Carousel.Next>Next</Carousel.Next>
</Carousel.Root>
```

### React
Use the React primitive adapter when Carousel state participates in React rendering.
```tsx
import { Carousel } from "@starwind-ui/react/carousel";

export function Example() {
  return (
    <Carousel.Root>
      <Carousel.Viewport>
        <Carousel.Container>
          <Carousel.Item>Slide 1</Carousel.Item>
        </Carousel.Container>
      </Carousel.Viewport>
      <Carousel.Previous>Previous</Carousel.Previous>
      <Carousel.Next>Next</Carousel.Next>
    </Carousel.Root>
  );
}
```

### HTML
Render the Carousel data-sw-* contract yourself, then initialize createCarousel.
```html
<div data-sw-carousel role="region" aria-roledescription="carousel">
  <div data-sw-carousel-viewport>
    <div data-sw-carousel-container>
      <div data-sw-carousel-item role="group" aria-roledescription="slide">Slide 1</div>
    </div>
  </div>
  <button data-sw-carousel-previous type="button">Previous</button>
  <button data-sw-carousel-next type="button">Next</button>
</div>

const root = document.querySelector("[data-sw-carousel]");
  if (root) {
    createCarousel(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Carousel Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-carousel` |
| Role | `region` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| orientation | `"horizontal" \| "vertical"` | "horizontal" | option | Sets the Carousel orientation. | - |
| opts | `CarouselOptions["opts"]` | {} | option | Passes options to the underlying carousel engine. | - |
| plugins | `CarouselOptions["plugins"]` | - | option | Passes plugins to the underlying carousel engine. | - |
| setApi | `(api: CarouselInstance["api"]) => void` | - | callback | Receives the carousel API instance when it is ready. | - |
| autoInit | `boolean` | true | option | Initializes the carousel automatically when the page loads. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-axis` | prop | - | Reflects the axis prop on the Root part. |
| `data-opts` | prop | - | Reflects the opts prop on the Root part. |
| `data-auto-init` | prop | - | Reflects the auto init prop on the Root part. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel`, `role`, `aria-roledescription`, `data-axis`, `data-opts`, `data-auto-init` | The carousel root needs region semantics, orientation, options, and optional auto-init control before the Embla runtime attaches. |

### Viewport
The visible viewport for Carousel content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-carousel-viewport` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel-viewport` | Embla needs a viewport element to measure visible slides. |

### Container
Groups the scrolling or moving content for Carousel.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-carousel-container` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel-container` | runtime | - | Marks the Container part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| container | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel-container` | Embla uses the container as the translated slide rail. |

### Item
An interactive item inside the Carousel collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-carousel-item` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel-item`, `role`, `aria-roledescription` | Carousel items need a stable marker and slide semantics for generated anatomy. |

### Previous
Moves Carousel to the previous item or slide.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-carousel-previous` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel-previous` | runtime | - | Marks the Previous part so Starwind Runtime can find it. |
| `data-disabled` | state | - | Reflects the disabled state on the Previous part. |
#### Refs
| Part | Public |
| --- | --- |
| previous | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel-previous`, `type`, `aria-disabled`, `data-disabled` | The previous control needs a discovery marker and safe button type before hydration. |

### Next
Moves Carousel to the next item or slide.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-carousel-next` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel-next` | runtime | - | Marks the Next part so Starwind Runtime can find it. |
| `data-disabled` | state | - | Reflects the disabled state on the Next part. |
#### Refs
| Part | Public |
| --- | --- |
| next | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel-next`, `type`, `aria-disabled`, `data-disabled` | The next control needs a discovery marker and safe button type before hydration. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createCarousel`](/docs/runtime/#create-carousel) |
| Import | `@starwind-ui/runtime/carousel` |
| Root part | root |
| Option props | orientation, opts, plugins, setApi |
| Option lifecycles | orientation: refresh-required, opts: refresh-required, plugins: refresh-required, setApi: constructor-only |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Carousel](/docs/components/carousel/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/carousel` | `createCarousel` |
| Astro Primitive | `@starwind-ui/astro/carousel` | `Carousel`, `CarouselRoot`, `CarouselViewport`, `CarouselContainer`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` |
| React Primitive | `@starwind-ui/react/carousel` | `Carousel`, `CarouselRoot`, `CarouselViewport`, `CarouselContainer`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Carousel` |
| runtime-factory | `createCarousel` |
| part | `Carousel.Root` |
| part | `Carousel.Viewport` |
| part | `Carousel.Container` |
| part | `Carousel.Item` |
| part | `Carousel.Previous` |
| part | `Carousel.Next` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced carousel navigation, orientation, looping, slide state, and plugin lifecycle coordination.

---

Source: [https://starwind.dev/docs/primitives/checkbox/](https://starwind.dev/docs/primitives/checkbox/) · [Markdown](https://starwind.dev/docs/primitives/checkbox.md)

# Checkbox Primitive

Checkbox coordinates a visible boolean control, indicator presence, and hidden form inputs for boolean form state.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Usage Guidelines
- **Use Checkbox for one independent boolean value.** Use Checkbox when users can turn a single option on or off without choosing from a required set.
- **Use the hidden input parts for form submission.** The runtime synchronizes the hidden native input and unchecked input so unchecked and checked states can submit predictable values.
## Anatomy
### Astro
Use the Astro primitive adapter to render Checkbox anatomy with the Runtime wiring included.
```astro
---
import { Checkbox } from "@starwind-ui/astro/checkbox";
---

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

### React
Use the React primitive adapter when Checkbox state participates in React rendering.
```tsx
import { Checkbox } from "@starwind-ui/react/checkbox";

export function Example() {
  return (
    <Checkbox.Root>
      <Checkbox.Indicator />
    </Checkbox.Root>
  );
}
```

### HTML
Render the Checkbox data-sw-* contract yourself, then initialize createCheckbox.
```html
<span data-sw-checkbox role="checkbox">
  <span data-sw-checkbox-indicator></span>
  <input data-sw-checkbox-input type="checkbox" aria-hidden="true" tabindex="-1" />
</span>

const root = document.querySelector("[data-sw-checkbox]");
  if (root) {
    createCheckbox(root);
  }
</script>
```
## API Reference
### Root
The focusable checkbox control. It owns the Runtime instance and carries ARIA, checked, indeterminate, disabled, and form option state.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-checkbox` |
| Role | `checkbox` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| checked | `boolean` | - | control | Controls the checked state when a framework adapter owns it. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| defaultChecked | `boolean` | false | control | Sets the initial uncontrolled checked state. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| disabled | `boolean` | false | option | Prevents interaction and marks the control disabled. | - |
| form | `string` | - | option | Associates the hidden native input with an external form. | - |
| id | `string` | - | option | Sets the hidden native input id. | - |
| indeterminate | `boolean` | false | control | Sets the mixed visual state independently from checked state. | **React:** Use indeterminate for controlled state.<br>**Astro:** Use indeterminate for initial state and call setIndeterminate for later updates.<br>**Runtime / HTML:** Use data-indeterminate for initial state and call setIndeterminate for later updates. |
| name | `string` | - | option | Sets the submitted form field name. | - |
| nativeButton | `boolean` | false | rendering | Renders the root as a native button instead of a span. | - |
| readOnly | `boolean` | false | option | Marks the checkbox readonly for assistive technology. | - |
| required | `boolean` | false | option | Marks the form control as required. | - |
| uncheckedValue | `string` | - | option | Value submitted by the runtime-created unchecked input. | - |
| value | `string` | - | option | Value submitted by the checked input. | - |
| onCheckedChange | `(checked: boolean, details: CheckboxCheckedChangeDetails) => void` | - | callback | Receives checked-change details before state commits. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-checkbox` | runtime | - | Runtime discovery hook for the checkbox root. |
| `data-checked` | state | - | Present when the checkbox is checked. |
| `data-default-checked` | prop | - | Initial uncontrolled checked state. |
| `data-disabled` | prop | - | Present when the checkbox is disabled. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-id` | prop | - | Reflects the id prop on the Root part. |
| `data-indeterminate` | state | - | Present when the checkbox is in the mixed state. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
| `data-unchecked` | state | - | Present when the checkbox is unchecked. |
| `data-unchecked-value` | prop | - | Reflects the unchecked value prop on the Root part. |
| `data-value` | prop | - | Reflects the value prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | `getChecked` | `setChecked` | Tracks whether Checkbox is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| indeterminate | `boolean` | indeterminate | - | `data-indeterminate` | - | `setIndeterminate` | Tracks whether Checkbox is in a mixed state. | **React:** Use indeterminate for controlled state.<br>**Astro:** Use indeterminate for initial state and call setIndeterminate for later updates.<br>**Runtime / HTML:** Use data-indeterminate for initial state and call setIndeterminate for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checkedChange | onCheckedChange | starwind:checked-change | checked: `boolean` | CheckboxCheckedChangeDetails | before-state-commit | Yes | Fires when the checked state changes for Checkbox. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setChecked` | state: checked | emit: false | Yes | Updates whether Checkbox is checked from Runtime code. |
| `setIndeterminate` | state: indeterminate | emit: false | Yes | Updates whether Checkbox is in a mixed state from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Checkbox is disabled from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| checkbox-group | consumes | disabled, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-checkbox`, `role`, `aria-checked`, `data-checked`, `data-unchecked`, `data-default-checked`, `data-disabled`, `data-indeterminate` | The visible ARIA control needs correct semantics before controller hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |

### Indicator
The visual indicator rendered inside the root for checked or mixed state.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-checkbox-indicator` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| keepMounted | `boolean` | false | rendering | Keeps the indicator element mounted when unchecked. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-checkbox-indicator` | runtime | - | Runtime discovery hook for the indicator part. |
| `data-keep-mounted` | prop | - | Marks that the indicator should stay mounted when unchecked. |
| `data-unchecked` | state | - | Present while the checkbox is unchecked. |
#### Refs
| Part | Public |
| --- | --- |
| indicator | Yes |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | keepMounted |

### Input
The hidden native checkbox input synchronized by the Runtime for form submission.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-checkbox-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-checkbox-input` | runtime | - | Runtime discovery hook for the hidden checked input. |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-checkbox-input` | The runtime needs the nested input placeholder so it can attach form state after hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |

### Unchecked Input
The hidden unchecked input created or synchronized by the Runtime when unchecked values are needed.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-checkbox-unchecked-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-checkbox-unchecked-input` | runtime | - | Runtime discovery hook for the hidden unchecked input. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createCheckbox`](/docs/runtime/#create-checkbox) |
| Import | `@starwind-ui/runtime/checkbox` |
| Root part | root |
| Option props | checked, defaultChecked, disabled, form, id, indeterminate, name, readOnly, required, uncheckedValue, value |
| Option lifecycles | - |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Checkbox](/docs/components/checkbox/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/checkbox` | `createCheckbox` |
| Astro Primitive | `@starwind-ui/astro/checkbox` | `Checkbox`, `CheckboxRoot`, `CheckboxIndicator` |
| React Primitive | `@starwind-ui/react/checkbox` | `Checkbox`, `CheckboxRoot`, `CheckboxIndicator` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Checkbox` |
| runtime-factory | `createCheckbox` |
| part | `Checkbox.Root` |
| part | `Checkbox.Indicator` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.1
- Corrected React indicator presence for active, kept, and explicitly hidden indicators.
### v0.1.0
- Introduced checked and indeterminate state, form participation, and checked-change events.

---

Source: [https://starwind.dev/docs/primitives/checkbox-group/](https://starwind.dev/docs/primitives/checkbox-group/) · [Markdown](https://starwind.dev/docs/primitives/checkbox-group.md)

# Checkbox Group Primitive

Checkbox Group is a Starwind Runtime primitive in the controlled-value-group contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render CheckboxGroup anatomy with the Runtime wiring included.
```astro
---
import { CheckboxGroup } from "@starwind-ui/astro/checkbox-group";
---

<CheckboxGroup.Root />
```

### React
Use the React primitive adapter when CheckboxGroup state participates in React rendering.
```tsx
import { CheckboxGroup } from "@starwind-ui/react/checkbox-group";

export function Example() {
  return (
    <CheckboxGroup.Root />
  );
}
```

### HTML
Render the CheckboxGroup data-sw-* contract yourself, then initialize createCheckboxGroup.
```html
<div data-sw-checkbox-group role="group"></div>

const root = document.querySelector("[data-sw-checkbox-group]");
  if (root) {
    createCheckboxGroup(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Checkbox Group Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-checkbox-group` |
| Role | `group` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `CheckboxGroupValue` | - | control | Controls the current Checkbox Group value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `CheckboxGroupValue` | - | control | Sets the initial Checkbox Group value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| onValueChange | `(value: CheckboxGroupValue, details: CheckboxGroupValueChangeDetails) => void` | - | callback | Runs when the Checkbox Group value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-checkbox-group` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-value` | state | - | Reflects the value state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `CheckboxGroupValue` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Checkbox Group value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `CheckboxGroupValue` | CheckboxGroupValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Checkbox Group. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Checkbox Group value from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Checkbox Group is disabled from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| checkbox-group | provides | disabled, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-checkbox-group`, `role`, `data-default-value`, `data-disabled`, `data-value` | The checkbox group needs initial selection and disabled state for child checkbox styling before hydration. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createCheckboxGroup`](/docs/runtime/#create-checkbox-group) |
| Import | `@starwind-ui/runtime/checkbox-group` |
| Root part | root |
| Option props | defaultValue, disabled, value |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Checkbox Group](/docs/components/checkbox-group/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/checkbox-group` | `createCheckboxGroup` |
| Astro Primitive | `@starwind-ui/astro/checkbox-group` | `CheckboxGroup`, `CheckboxGroupRoot` |
| React Primitive | `@starwind-ui/react/checkbox-group` | `CheckboxGroup`, `CheckboxGroupRoot` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `CheckboxGroup` |
| runtime-factory | `createCheckboxGroup` |
| part | `CheckboxGroup.Root` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced grouped checkbox value ownership, shared disabled state, and form participation.

---

Source: [https://starwind.dev/docs/primitives/collapsible/](https://starwind.dev/docs/primitives/collapsible/) · [Markdown](https://starwind.dev/docs/primitives/collapsible.md)

# Collapsible Primitive

Collapsible is a Starwind Runtime primitive in the presence-disclosure-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Collapsible anatomy with the Runtime wiring included.
```astro
---
import { Collapsible } from "@starwind-ui/astro/collapsible";
---

<Collapsible.Root>
  <Collapsible.Trigger>Toggle details</Collapsible.Trigger>
  <Collapsible.Panel>Collapsible content</Collapsible.Panel>
</Collapsible.Root>
```

### React
Use the React primitive adapter when Collapsible state participates in React rendering.
```tsx
import { Collapsible } from "@starwind-ui/react/collapsible";

export function Example() {
  return (
    <Collapsible.Root>
      <Collapsible.Trigger>Toggle details</Collapsible.Trigger>
      <Collapsible.Panel>Collapsible content</Collapsible.Panel>
    </Collapsible.Root>
  );
}
```

### HTML
Render the Collapsible data-sw-* contract yourself, then initialize createCollapsible.
```html
<div data-sw-collapsible>
  <button data-sw-collapsible-trigger>Toggle details</button>
  <div data-sw-collapsible-panel hidden>Collapsible content</div>
</div>

const root = document.querySelector("[data-sw-collapsible]");
  if (root) {
    createCollapsible(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Collapsible Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-collapsible` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Collapsible is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Collapsible starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| onOpenChange | `(open: boolean, details: CollapsibleOpenChangeDetails) => void` | - | callback | Runs when Collapsible opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-collapsible` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Collapsible is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | CollapsibleOpenChangeDetails | before-state-commit | Yes | Fires when Collapsible opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Collapsible from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-collapsible`, `data-default-open`, `data-disabled`, `data-state` | The disclosure root needs initial open/closed state for styling before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Collapsible content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-collapsible-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | false | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-collapsible-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-collapsible-trigger`, `aria-expanded`, `data-state` | The trigger starts with stable disclosure affordances; the runtime wires ids and aria-controls after initialization. |

### Panel
The content panel controlled by Collapsible.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-collapsible-panel` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| hiddenUntilFound | `boolean` | false | rendering | Changes how the Panel part is rendered. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-collapsible-panel` | runtime | - | Marks the Panel part so Starwind Runtime can find it. |
| `data-hidden-until-found` | prop | - | Reflects the hidden until found prop on the Panel part. |
| `data-state` | state | - | Reflects the current state on the Panel part. |
#### Refs
| Part | Public |
| --- | --- |
| panel | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-collapsible-panel`, `data-hidden-until-found`, `data-state`, `hidden` | The panel starts hidden and is revealed or animated by the runtime controller; hidden-until-found keeps opted-in closed panels discoverable by browser find-in-page. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createCollapsible`](/docs/runtime/#create-collapsible) |
| Import | `@starwind-ui/runtime/collapsible` |
| Root part | root |
| Option props | defaultOpen, disabled, open |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Collapsible](/docs/components/collapsible/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/collapsible` | `createCollapsible` |
| Astro Primitive | `@starwind-ui/astro/collapsible` | `Collapsible`, `CollapsibleRoot`, `CollapsibleTrigger`, `CollapsiblePanel` |
| React Primitive | `@starwind-ui/react/collapsible` | `Collapsible`, `CollapsibleRoot`, `CollapsibleTrigger`, `CollapsiblePanel` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Collapsible` |
| runtime-factory | `createCollapsible` |
| part | `Collapsible.Root` |
| part | `Collapsible.Trigger` |
| part | `Collapsible.Panel` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced controlled and uncontrolled open state with trigger and panel presence.

---

Source: [https://starwind.dev/docs/primitives/color-picker/](https://starwind.dev/docs/primitives/color-picker/) · [Markdown](https://starwind.dev/docs/primitives/color-picker.md)

# Color Picker Primitive

Color Picker coordinates color parsing, two-dimensional area input, channel controls, editable values, presets, and native form submission.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Usage Guidelines
- **Compose only the controls your picker needs.** Area, channel, text-entry, format, swatch, clear, and EyeDropper parts share one Root state model and can be arranged for the product workflow.
- **Use HiddenInput for native forms.** It is the sole submitting control and carries the accepted canonical color string, name, form association, and required state.
- **Choose one format-control path.** Use FormatSelect for native progressive enhancement or place one Select Root inside FormatControl for a composite popup. Both edit the same hex, rgb, hsl, or hsb format state.
- **Start with the styled Color Picker for product UI.** The related styled component composes Popover, Select, and Native Select around this Primitive contract; use the Primitive parts when you need custom anatomy.
## Anatomy
### Astro
Use the Astro primitive adapter to render Color Picker anatomy with the Runtime wiring included.
```astro
---
import { ColorPicker } from "@starwind-ui/astro/color-picker";
---

<ColorPicker.Root>
  <ColorPicker.Label>Color</ColorPicker.Label>
  <ColorPicker.Control>
    <ColorPicker.ValueSwatch />
    <ColorPicker.ValueInput />
    <ColorPicker.ValueText />
  </ColorPicker.Control>
  <ColorPicker.Area xChannel="saturation" yChannel="brightness">
    <ColorPicker.AreaBackground />
    <ColorPicker.AreaThumb />
    <ColorPicker.AreaInput axis="x" />
    <ColorPicker.AreaInput axis="y" />
  </ColorPicker.Area>
  <ColorPicker.ChannelSlider channel="hue">
    <ColorPicker.ChannelSliderTrack />
    <ColorPicker.ChannelSliderThumb />
    <ColorPicker.ChannelSliderInput />
  </ColorPicker.ChannelSlider>
  <ColorPicker.ChannelInput channel="hue" />
  <ColorPicker.FormatSelect />
  <ColorPicker.FormatControl />
  <ColorPicker.TransparencyGrid />
  <ColorPicker.SwatchGroup>
    <ColorPicker.Swatch swatchValue="#3b82f6" />
  </ColorPicker.SwatchGroup>
  <ColorPicker.EyeDropperTrigger>Pick from screen</ColorPicker.EyeDropperTrigger>
  <ColorPicker.Clear>Clear</ColorPicker.Clear>
  <ColorPicker.HiddenInput />
</ColorPicker.Root>
```

### React
Use the React primitive adapter when Color Picker state participates in React rendering.
```tsx
import { ColorPicker } from "@starwind-ui/react/color-picker";

export function Example() {
  return (
    <ColorPicker.Root>
      <ColorPicker.Label>Color</ColorPicker.Label>
      <ColorPicker.Control>
        <ColorPicker.ValueSwatch />
        <ColorPicker.ValueInput />
        <ColorPicker.ValueText />
      </ColorPicker.Control>
      <ColorPicker.Area xChannel="saturation" yChannel="brightness">
        <ColorPicker.AreaBackground />
        <ColorPicker.AreaThumb />
        <ColorPicker.AreaInput axis="x" />
        <ColorPicker.AreaInput axis="y" />
      </ColorPicker.Area>
      <ColorPicker.ChannelSlider channel="hue">
        <ColorPicker.ChannelSliderTrack />
        <ColorPicker.ChannelSliderThumb />
        <ColorPicker.ChannelSliderInput />
      </ColorPicker.ChannelSlider>
      <ColorPicker.ChannelInput channel="hue" />
      <ColorPicker.FormatSelect />
      <ColorPicker.FormatControl />
      <ColorPicker.TransparencyGrid />
      <ColorPicker.SwatchGroup>
        <ColorPicker.Swatch swatchValue="#3b82f6" />
      </ColorPicker.SwatchGroup>
      <ColorPicker.EyeDropperTrigger>Pick from screen</ColorPicker.EyeDropperTrigger>
      <ColorPicker.Clear>Clear</ColorPicker.Clear>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  );
}
```

### HTML
Render the Color Picker data-sw-* contract yourself, then initialize createColorPicker.
```html
<div data-sw-color-picker role="group">
  <span data-sw-color-picker-label>Color</span>
  <div data-sw-color-picker-control>
    <span data-sw-color-picker-value-swatch></span>
    <input data-sw-color-picker-value-input />
    <span data-sw-color-picker-value-text></span>
  </div>
  <div data-sw-color-picker-area data-x-channel="saturation" data-y-channel="brightness">
    <div data-sw-color-picker-area-background></div>
    <span data-sw-color-picker-area-thumb></span>
    <input data-sw-color-picker-area-input type="range" data-axis="x" />
    <input data-sw-color-picker-area-input type="range" data-axis="y" />
  </div>
  <div data-sw-color-picker-channel-slider data-channel="hue">
    <div data-sw-color-picker-channel-slider-track></div>
    <span data-sw-color-picker-channel-slider-thumb></span>
    <input data-sw-color-picker-channel-input type="range" />
  </div>
  <input data-sw-color-picker-channel-field data-channel="hue" />
  <select data-sw-color-picker-format-select></select>
  <div data-sw-color-picker-format-control></div>
  <span data-sw-color-picker-transparency-grid></span>
  <div data-sw-color-picker-swatch-group role="group">
    <button data-sw-color-picker-swatch type="button" data-value="#3b82f6"></button>
  </div>
  <button data-sw-color-picker-eye-dropper type="button" hidden>Pick from screen</button>
  <button data-sw-color-picker-clear type="button">Clear</button>
  <input data-sw-color-picker-hidden-input type="text" aria-hidden="true" tabindex="-1" />
</div>

<ColorPicker.Root defaultValue="#3b82f6" format="hex" name="accent">
  <ColorPicker.ValueInput />
  <ColorPicker.FormatControl>
    <Select.Root defaultValue="hex">
      <Select.Trigger aria-label="Color format">
        <Select.Value>HEX</Select.Value>
      </Select.Trigger>
      <Select.Positioner>
        <Select.Popup>
          <Select.List>
            <Select.Item value="hex"><Select.ItemText>HEX</Select.ItemText></Select.Item>
            <Select.Item value="rgb"><Select.ItemText>RGB</Select.ItemText></Select.Item>
            <Select.Item value="hsl"><Select.ItemText>HSL</Select.ItemText></Select.Item>
            <Select.Item value="hsb"><Select.ItemText>HSB</Select.ItemText></Select.Item>
          </Select.List>
        </Select.Popup>
      </Select.Positioner>
    </Select.Root>
  </ColorPicker.FormatControl>
  <ColorPicker.HiddenInput />
</ColorPicker.Root>
```

#### React
```tsx
import { ColorPicker } from "@starwind-ui/react/color-picker";
import { Select } from "@starwind-ui/react/select";

export function CompositeFormatControl() {
  return (
    <ColorPicker.Root defaultValue="#3b82f6" format="hex" name="accent">
      <ColorPicker.ValueInput />
      <ColorPicker.FormatControl>
        <Select.Root defaultValue="hex">
          <Select.Trigger aria-label="Color format">
            <Select.Value>HEX</Select.Value>
          </Select.Trigger>
          <Select.Positioner>
            <Select.Popup>
              <Select.List>
                <Select.Item value="hex"><Select.ItemText>HEX</Select.ItemText></Select.Item>
                <Select.Item value="rgb"><Select.ItemText>RGB</Select.ItemText></Select.Item>
                <Select.Item value="hsl"><Select.ItemText>HSL</Select.ItemText></Select.Item>
                <Select.Item value="hsb"><Select.ItemText>HSB</Select.ItemText></Select.Item>
              </Select.List>
            </Select.Popup>
          </Select.Positioner>
        </Select.Root>
      </ColorPicker.FormatControl>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  );
}
```

#### HTML
```html
<div data-sw-color-picker role="group">
  <input data-sw-color-picker-value-input value="#3b82f6" />
  <div data-sw-color-picker-format-control>
    <div data-sw-select data-default-value="hex">
      <button data-sw-select-trigger type="button" aria-label="Color format">
        <span data-sw-select-value>HEX</span>
      </button>
      <div data-sw-select-positioner>
        <div data-sw-select-popup hidden>
          <div data-sw-select-list>
            <div data-sw-select-item data-value="hex"><span data-sw-select-item-text>HEX</span></div>
            <div data-sw-select-item data-value="rgb"><span data-sw-select-item-text>RGB</span></div>
            <div data-sw-select-item data-value="hsl"><span data-sw-select-item-text>HSL</span></div>
            <div data-sw-select-item data-value="hsb"><span data-sw-select-item-text>HSB</span></div>
          </div>
        </div>
      </div>
      <input data-sw-select-input type="hidden" />
    </div>
  </div>
  <input data-sw-color-picker-hidden-input type="text" name="accent" aria-hidden="true" tabindex="-1" />
</div>

<ColorPicker.Root defaultValue="#3b82f6" format="hex" name="accent">
  <ColorPicker.ValueInput />
  <ColorPicker.FormatSelect aria-label="Color format">
    <option value="hex">HEX</option>
    <option value="rgb">RGB</option>
    <option value="hsl">HSL</option>
    <option value="hsb">HSB</option>
  </ColorPicker.FormatSelect>
  <ColorPicker.HiddenInput />
</ColorPicker.Root>
```

#### React
```tsx
import { ColorPicker } from "@starwind-ui/react/color-picker";

export function NativeFormatSelect() {
  return (
    <ColorPicker.Root defaultValue="#3b82f6" format="hex" name="accent">
      <ColorPicker.ValueInput />
      <ColorPicker.FormatSelect aria-label="Color format">
        <option value="hex">HEX</option>
        <option value="rgb">RGB</option>
        <option value="hsl">HSL</option>
        <option value="hsb">HSB</option>
      </ColorPicker.FormatSelect>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  );
}
```

#### HTML
```html
<div data-sw-color-picker role="group">
  <input data-sw-color-picker-value-input value="#3b82f6" />
  <select data-sw-color-picker-format-select aria-label="Color format">
    <option value="hex">HEX</option>
    <option value="rgb">RGB</option>
    <option value="hsl">HSL</option>
    <option value="hsb">HSB</option>
  </select>
  <input data-sw-color-picker-hidden-input type="text" name="accent" aria-hidden="true" tabindex="-1" />
</div>

const root = document.querySelector("[data-sw-color-picker]");
  if (root) {
    createColorPicker(root, {
      defaultValue: "#3b82f6",
      format: "hex",
      name: "accent",
    });
  }
</script>
```

## State, Events, and Commands
The `value` and `format` state models are reflected across every owned part. Listen for cancellable `starwind:value-change`, committed `starwind:value-committed`, and post-commit `starwind:format-change` events on Root. Use the controller setters for application state; `setValue` and `setFormat` accept `{ emit: false }` for silent synchronization. For a composite control, Color Picker internally sends `starwind:set-value`, `starwind:set-disabled`, and `starwind:set-readonly` commands to the nested Select. A canceled Select value change is ignored, and its nested value event does not escape as a Color Picker value event.

## Forms and Reset
HiddenInput is the sole submitted color field. Keep `name`, `form`, and `required` on Color Picker Root rather than either format control; Runtime removes form ownership from the composite Select. Native form reset restores the initial value and format, clears drafts, and silently reconciles both native and composite controls.

## Styling Color Thumbs
Runtime writes `--sw-color-picker-area-thumb-color` on AreaThumb and `--sw-color-picker-channel-thumb-color` on ChannelSliderThumb. The area value is opaque, ordinary channel thumbs use the accepted color, alpha preserves transparency, and empty values clear both variables. Paint an inner layer from these variables so the thumb remains visible at track boundaries without changing its position or interaction geometry.

## Accessibility
Area and channel controls expose native range inputs for keyboard operation. Swatches are native buttons with selected state reflected through `aria-pressed`. Give FormatSelect an accessible label; for FormatControl, label the nested Select Trigger and let Select own combobox and listbox semantics. Supply localized value and color descriptions with `getAriaValueText`, `getAreaRoleDescription`, and `getColorDescription` when the defaults do not fit your interface.
## API Reference
### Root
Owns the Color Picker Runtime controller and shared value, format, interaction, locale, and form options.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker` |
| Role | `group` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `ColorPickerValue` | - | control | Controls the accepted color value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `ColorPickerValue` | "#000000" | control | Sets the initial uncontrolled color value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| format | `ColorPickerFormat` | "hex" | control | Controls the color string format. | **React:** Use format for controlled state, and onFormatChange for state changes.<br>**Astro:** Use format for initial state, listen for starwind:format-change, and call setFormat for later updates.<br>**Runtime / HTML:** Use data-format for initial state, listen for starwind:format-change, and call setFormat for later updates. |
| alpha | `boolean` | true | option | Enables alpha-channel editing. | - |
| allowEmpty | `boolean` | false | option | Allows the accepted value to be null. | - |
| disabled | `boolean` | false | option | Disables every interactive picker part. | - |
| readOnly | `boolean` | false | option | Prevents edits while preserving focus and value inspection. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| form | `string` | - | option | Associates the hidden input with an external form. | - |
| required | `boolean` | false | option | Marks the hidden form input as required. | - |
| locale | `string` | - | option | Sets the locale used for accessible color descriptions. | - |
| dir | `ColorPickerDirection` | - | option | Sets left-to-right or right-to-left direction explicitly. | - |
| getAriaValueText | `ColorPickerOptions['getAriaValueText']` | - | option | Customizes accessible range value text. | - |
| getAreaRoleDescription | `ColorPickerOptions['getAreaRoleDescription']` | - | option | Customizes the color-area role description. | - |
| getColorDescription | `ColorPickerOptions['getColorDescription']` | - | option | Customizes the accessible description of a color. | - |
| onValueChange | `(value: ColorPickerColor \| null, details: ColorPickerValueChangeDetails) => void` | - | callback | Receives cancellable continuous value-change details before commit. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| onValueCommitted | `(value: ColorPickerColor \| null, details: ColorPickerValueCommitDetails) => void` | - | callback | Receives the accepted value when an interaction commits. | - |
| onFormatChange | `(format: ColorPickerFormat, details: ColorPickerFormatChangeDetails) => void` | - | callback | Receives the accepted format after it changes. | **React:** Use format for controlled state, and onFormatChange for state changes.<br>**Astro:** Use format for initial state, listen for starwind:format-change, and call setFormat for later updates.<br>**Runtime / HTML:** Use data-format for initial state, listen for starwind:format-change, and call setFormat for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-value` | state | - | Reflects the value state on the Root part. |
| `data-format` | state | - | Reflects the format state on the Root part. |
| `data-alpha` | prop | - | Reflects the alpha prop on the Root part. |
| `data-allow-empty` | prop | - | Reflects the allow empty prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-invalid` | state | - | Reflects the invalid state on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
| `data-locale` | prop | - | Reflects the locale prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `ColorPickerColor \| null` | value | defaultValue | `data-value` | `getValue` | `setValue` | The accepted immutable color value, or null when empty values are allowed. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| format | `ColorPickerFormat` | format | - | `data-format` | `getFormat` | `setFormat` | The accepted color string format used by editable and display parts. | **React:** Use format for controlled state, and onFormatChange for state changes.<br>**Astro:** Use format for initial state, listen for starwind:format-change, and call setFormat for later updates.<br>**Runtime / HTML:** Use data-format for initial state, listen for starwind:format-change, and call setFormat for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `ColorPickerColor \| null` | ColorPickerValueChangeDetails | before-state-commit | Yes | Cancelable continuous change emitted before a proposed value commits. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| valueCommitted | onValueCommitted | starwind:value-committed | value: `ColorPickerColor \| null` | ColorPickerValueCommitDetails | after-state-commit | - | Emitted after an accepted interaction value commits. | - |
| formatChange | onFormatChange | starwind:format-change | format: `ColorPickerFormat` | ColorPickerFormatChangeDetails | after-state-commit | - | Emitted after the accepted string format changes. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Synchronizes the accepted value and can suppress event emission. |
| `setFormat` | state: format | emit: false | Yes | Synchronizes the accepted format and can suppress event emission. |
| `setDisabled` | prop: disabled | - | No | Updates disabled state across every interactive part. |
| `setReadOnly` | prop: readOnly | - | No | Updates readonly state across editable parts. |
| `setName` | prop: name | - | No | Updates the hidden input's form field name. |
| `setOptions` | props: alpha, allowEmpty, dir, form, getAreaRoleDescription, getAriaValueText, getColorDescription, locale, required | - | No | Refreshes mutable locale, direction, accessibility, alpha, empty, and form options. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-color-picker`, `role`, `data-value`, `data-format`, `data-alpha`, `data-allow-empty`, `data-disabled`, `data-readonly`, `data-invalid`, `data-name`, `data-form`, `data-required`, `data-locale`, `dir` | Initial value, capability, form, and interaction state must be styleable before Runtime initialization. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, name, required, value |
| Hidden input | hiddenInput (text) |

### Label
Labels the color picker.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |

### Control
Groups the visible picker controls.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-control` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-control` | runtime | - | Marks the Control part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| control | Yes |

### Value Input
Accepts and validates a complete color string draft.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-color-picker-value-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-value-input` | runtime | - | Marks the Value Input part so Starwind Runtime can find it. |
| `data-invalid` | state | - | Reflects the invalid state on the Value Input part. |
#### Refs
| Part | Public |
| --- | --- |
| valueInput | Yes |

### Value Swatch
Displays the currently accepted color.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-value-swatch` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-value-swatch` | runtime | - | Marks the Value Swatch part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| valueSwatch | Yes |

### Value Text
Displays the currently accepted color as text.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-value-text` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-value-text` | runtime | - | Marks the Value Text part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| valueText | Yes |

### Area
Coordinates two color channels across horizontal and vertical axes.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-area` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| xChannel | `ColorPickerChannel` | - | attribute | Selects the channel controlled by the horizontal axis. | - |
| yChannel | `ColorPickerChannel` | - | attribute | Selects the channel controlled by the vertical axis. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-area` | runtime | - | Marks the Area part so Starwind Runtime can find it. |
| `data-x-channel` | prop | - | Reflects the x channel prop on the Area part. |
| `data-y-channel` | prop | - | Reflects the y channel prop on the Area part. |
| `data-focused` | state | - | Reflects the focused state on the Area part. |
| `data-dragging` | state | - | Reflects the dragging state on the Area part. |
| `data-disabled` | state | - | Reflects the disabled state on the Area part. |
| `data-readonly` | state | - | Reflects the readonly state on the Area part. |
#### Refs
| Part | Public |
| --- | --- |
| area | Yes |

### Area Background
Paints the two-dimensional color-area background.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-area-background` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-area-background` | runtime | - | Marks the Area Background part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| areaBackground | Yes |

### Area Thumb
Shows the accepted position in the color area.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-area-thumb` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-area-thumb` | runtime | - | Marks the Area Thumb part so Starwind Runtime can find it. |
| `data-focused` | state | - | Reflects the focused state on the Area Thumb part. |
| `data-dragging` | state | - | Reflects the dragging state on the Area Thumb part. |
| `data-disabled` | state | - | Reflects the disabled state on the Area Thumb part. |
| `data-readonly` | state | - | Reflects the readonly state on the Area Thumb part. |
#### Refs
| Part | Public |
| --- | --- |
| areaThumb | Yes |

### Area Input
Provides a native range input for one color-area axis.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-color-picker-area-input` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| axis | `"x" \| "y"` | - | attribute | Selects the controlled area axis. | - |
| step | `number` | - | attribute | Sets the range step. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-area-input` | runtime | - | Marks the Area Input part so Starwind Runtime can find it. |
| `data-axis` | prop | - | Reflects the axis prop on the Area Input part. |
| `data-step` | prop | - | Reflects the step prop on the Area Input part. |
#### Refs
| Part | Public |
| --- | --- |
| areaInput | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-color-picker-area-input`, `type`, `data-axis`, `data-step`, `aria-roledescription`, `aria-valuetext`, `aria-description` | Both area axes expose native range semantics and accessible value context before enhancement. |

### Channel Slider
Coordinates one color channel along a horizontal or vertical track.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-channel-slider` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| channel | `ColorPickerChannel` | - | attribute | Selects the controlled color channel. | - |
| orientation | `"horizontal" \| "vertical"` | "horizontal" | attribute | Sets the slider orientation. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-channel-slider` | runtime | - | Marks the Channel Slider part so Starwind Runtime can find it. |
| `data-channel` | prop | - | Reflects the channel prop on the Channel Slider part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Channel Slider part. |
| `data-focused` | state | - | Reflects the focused state on the Channel Slider part. |
| `data-dragging` | state | - | Reflects the dragging state on the Channel Slider part. |
| `data-disabled` | state | - | Reflects the disabled state on the Channel Slider part. |
| `data-readonly` | state | - | Reflects the readonly state on the Channel Slider part. |
#### Refs
| Part | Public |
| --- | --- |
| channelSlider | Yes |

### Channel Slider Track
Paints the selected channel's range.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-channel-slider-track` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-channel-slider-track` | runtime | - | Marks the Channel Slider Track part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| channelSliderTrack | Yes |

### Channel Slider Thumb
Shows the accepted channel position.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-channel-slider-thumb` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-channel-slider-thumb` | runtime | - | Marks the Channel Slider Thumb part so Starwind Runtime can find it. |
| `data-focused` | state | - | Reflects the focused state on the Channel Slider Thumb part. |
| `data-dragging` | state | - | Reflects the dragging state on the Channel Slider Thumb part. |
| `data-disabled` | state | - | Reflects the disabled state on the Channel Slider Thumb part. |
| `data-readonly` | state | - | Reflects the readonly state on the Channel Slider Thumb part. |
#### Refs
| Part | Public |
| --- | --- |
| channelSliderThumb | Yes |

### Channel Slider Input
Provides the native range input for a channel slider.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-color-picker-channel-input` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| step | `number` | - | attribute | Sets the range step. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-channel-input` | runtime | - | Marks the Channel Slider Input part so Starwind Runtime can find it. |
| `data-step` | prop | - | Reflects the step prop on the Channel Slider Input part. |
#### Refs
| Part | Public |
| --- | --- |
| channelSliderInput | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-color-picker-channel-input`, `type`, `data-step`, `aria-valuetext`, `aria-description` | Each visual channel slider has a keyboard-operable native range control. |

### Channel Input
Accepts and validates a numeric channel draft.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-color-picker-channel-field` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| channel | `ColorPickerChannel` | - | attribute | Selects the edited color channel. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-channel-field` | runtime | - | Marks the Channel Input part so Starwind Runtime can find it. |
| `data-channel` | prop | - | Reflects the channel prop on the Channel Input part. |
| `data-invalid` | state | - | Reflects the invalid state on the Channel Input part. |
#### Refs
| Part | Public |
| --- | --- |
| channelInput | Yes |

### Format Select
The progressively enhanced native select for hex, rgb, hsl, and hsb editing formats.
| Fact | Value |
| --- | --- |
| Default element | `select` |
| Discovery hook | `data-sw-color-picker-format-select` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-format-select` | runtime | - | Runtime discovery hook for the native format control. |
#### Refs
| Part | Public |
| --- | --- |
| formatSelect | Yes |

### Format Control
Wraps one Runtime-backed Select Root as the composite format control without reimplementing Select behavior.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-format-control` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-format-control` | runtime | - | Runtime discovery hook for the composite format-control wrapper. |
| `data-format` | state | - | The accepted hex, rgb, hsl, or hsb editing format. |
| `data-disabled` | state | - | Present when Color Picker disables the composite Select. |
| `data-readonly` | state | - | Present when Color Picker makes the composite Select read-only. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| format | `ColorPickerFormat` | format | - | `data-format` | `getFormat` | `setFormat` | The accepted color string format used by editable and display parts. | **React:** Use format for controlled state, and onFormatChange for state changes.<br>**Astro:** Use format for initial state, listen for starwind:format-change, and call setFormat for later updates.<br>**Runtime / HTML:** Use data-format for initial state, listen for starwind:format-change, and call setFormat for later updates. |
#### Refs
| Part | Public |
| --- | --- |
| formatControl | Yes |

### Transparency Grid
Provides a checkerboard surface beneath translucent colors.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-transparency-grid` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-transparency-grid` | runtime | - | Marks the Transparency Grid part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| transparencyGrid | Yes |

### Swatch Group
Groups preset color swatches.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-swatch-group` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-swatch-group` | runtime | - | Marks the Swatch Group part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| swatchGroup | Yes |

### Swatch
Selects a preset color with native button semantics.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-color-picker-swatch` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| swatchValue | `ColorPickerValue` | - | attribute | Sets the preset color. | - |
| swatchDisabled | `boolean` | - | attribute | Disables this swatch. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-swatch` | runtime | - | Marks the Swatch part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Swatch part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Swatch part. |
| `data-selected` | state | - | Reflects the selected state on the Swatch part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `ColorPickerColor \| null` | value | defaultValue | `data-value` | `getValue` | `setValue` | The accepted immutable color value, or null when empty values are allowed. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Refs
| Part | Public |
| --- | --- |
| swatch | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-color-picker-swatch`, `type`, `data-value`, `data-disabled`, `data-selected`, `aria-pressed` | Preset selection is a native button with value, disabled, and selected semantics. |

### Eye Dropper Trigger
Opens the platform EyeDropper when that capability is available.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-color-picker-eye-dropper` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-eye-dropper` | runtime | - | Marks the Eye Dropper Trigger part so Starwind Runtime can find it. |
| `data-unsupported` | runtime | - | Marks the Eye Dropper Trigger part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| eyeDropperTrigger | Yes |

### Clear
Clears the value when empty values are allowed.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-color-picker-clear` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-clear` | runtime | - | Marks the Clear part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| clear | Yes |

### Hidden Input
The sole hidden native input used for form submission.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-color-picker-hidden-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-hidden-input` | runtime | - | Marks the Hidden Input part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| hiddenInput | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-color-picker-hidden-input`, `type`, `aria-hidden`, `tabIndex`, `name`, `form`, `required`, `value` | The sole submitting control carries the canonical color string and remains programmatically focusable for native required validation while staying visually hidden, outside the tab order, and hidden from assistive technology. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, name, required, value |
| Hidden input | hiddenInput (text) |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createColorPicker`](/docs/runtime/#create-color-picker) |
| Import | `@starwind-ui/runtime/color-picker` |
| Root part | root |
| Option props | value, defaultValue, format, alpha, allowEmpty, disabled, readOnly, name, form, required, locale, dir, getAriaValueText, getAreaRoleDescription, getColorDescription, onValueChange, onValueCommitted, onFormatChange |
| Option lifecycles | value: setter-backed, defaultValue: constructor-only, format: setter-backed, alpha: setter-backed, allowEmpty: setter-backed, disabled: setter-backed, readOnly: setter-backed, name: setter-backed, form: setter-backed, required: setter-backed, locale: setter-backed, dir: setter-backed, getAriaValueText: setter-backed, getAreaRoleDescription: setter-backed, getColorDescription: setter-backed, onValueChange: constructor-only, onValueCommitted: constructor-only, onFormatChange: constructor-only |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, name, required, value |
| Hidden input | hiddenInput (text) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Color Picker](/docs/components/color-picker/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/color-picker` | `createColorPicker` |
| Astro Primitive | `@starwind-ui/astro/color-picker` | `Color Picker`, `Color PickerRoot`, `Color PickerLabel`, `Color PickerControl`, `Color PickerValueInput`, `Color PickerValueSwatch`, `Color PickerValueText`, `Color PickerArea`, `Color PickerAreaBackground`, `Color PickerAreaThumb`, `Color PickerAreaInput`, `Color PickerChannelSlider`, `Color PickerChannelSliderTrack`, `Color PickerChannelSliderThumb`, `Color PickerChannelSliderInput`, `Color PickerChannelInput`, `Color PickerFormatSelect`, `Color PickerFormatControl`, `Color PickerTransparencyGrid`, `Color PickerSwatchGroup`, `Color PickerSwatch`, `Color PickerEyeDropperTrigger`, `Color PickerClear`, `Color PickerHiddenInput` |
| React Primitive | `@starwind-ui/react/color-picker` | `Color Picker`, `Color PickerRoot`, `Color PickerLabel`, `Color PickerControl`, `Color PickerValueInput`, `Color PickerValueSwatch`, `Color PickerValueText`, `Color PickerArea`, `Color PickerAreaBackground`, `Color PickerAreaThumb`, `Color PickerAreaInput`, `Color PickerChannelSlider`, `Color PickerChannelSliderTrack`, `Color PickerChannelSliderThumb`, `Color PickerChannelSliderInput`, `Color PickerChannelInput`, `Color PickerFormatSelect`, `Color PickerFormatControl`, `Color PickerTransparencyGrid`, `Color PickerSwatchGroup`, `Color PickerSwatch`, `Color PickerEyeDropperTrigger`, `Color PickerClear`, `Color PickerHiddenInput` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `ColorPicker` |
| runtime-factory | `createColorPicker` |
| part | `ColorPicker.Root` |
| part | `ColorPicker.Label` |
| part | `ColorPicker.Control` |
| part | `ColorPicker.ValueInput` |
| part | `ColorPicker.ValueSwatch` |
| part | `ColorPicker.ValueText` |
| part | `ColorPicker.Area` |
| part | `ColorPicker.AreaBackground` |
| part | `ColorPicker.AreaThumb` |
| part | `ColorPicker.AreaInput` |
| part | `ColorPicker.ChannelSlider` |
| part | `ColorPicker.ChannelSliderTrack` |
| part | `ColorPicker.ChannelSliderThumb` |
| part | `ColorPicker.ChannelSliderInput` |
| part | `ColorPicker.ChannelInput` |
| part | `ColorPicker.FormatSelect` |
| part | `ColorPicker.FormatControl` |
| part | `ColorPicker.TransparencyGrid` |
| part | `ColorPicker.SwatchGroup` |
| part | `ColorPicker.Swatch` |
| part | `ColorPicker.EyeDropperTrigger` |
| part | `ColorPicker.Clear` |
| part | `ColorPicker.HiddenInput` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced color state, format conversion, area and channel controls, swatches, and form participation.

---

Source: [https://starwind.dev/docs/primitives/combobox/](https://starwind.dev/docs/primitives/combobox/) · [Markdown](https://starwind.dev/docs/primitives/combobox.md)

# Combobox Primitive

Combobox is a Starwind Runtime primitive in the floating-value-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Combobox anatomy with the Runtime wiring included.
```astro
---
import { Combobox } from "@starwind-ui/astro/combobox";
---

<Combobox.Root>
  <Combobox.Label>Choose a framework</Combobox.Label>
  <Combobox.InputGroup>
    <Combobox.Input placeholder="Search frameworks" />
    <Combobox.Trigger>Open</Combobox.Trigger>
    <Combobox.Clear>Clear</Combobox.Clear>
  </Combobox.InputGroup>
  <Combobox.Positioner>
    <Combobox.Popup>
      <Combobox.Empty>No results</Combobox.Empty>
    </Combobox.Popup>
  </Combobox.Positioner>
</Combobox.Root>
```

### React
Use the React primitive adapter when Combobox state participates in React rendering.
```tsx
import { Combobox } from "@starwind-ui/react/combobox";

export function Example() {
  return (
    <Combobox.Root>
      <Combobox.Label>Choose a framework</Combobox.Label>
      <Combobox.InputGroup>
        <Combobox.Input placeholder="Search frameworks" />
        <Combobox.Trigger>Open</Combobox.Trigger>
        <Combobox.Clear>Clear</Combobox.Clear>
      </Combobox.InputGroup>
      <Combobox.Positioner>
        <Combobox.Popup>
          <Combobox.Empty>No results</Combobox.Empty>
        </Combobox.Popup>
      </Combobox.Positioner>
    </Combobox.Root>
  );
}
```

### HTML
Render the Combobox data-sw-* contract yourself, then initialize createCombobox.
```html
<div data-sw-combobox>
  <div data-sw-combobox-label>Choose a framework</div>
  <div data-sw-combobox-input-group>
    <input data-sw-combobox-input role="combobox" aria-autocomplete="list" autocomplete="off" placeholder="Search frameworks" />
    <button data-sw-combobox-trigger aria-haspopup="listbox">Open</button>
    <button data-sw-combobox-clear type="button">Clear</button>
  </div>
  <div data-sw-combobox-positioner>
    <div data-sw-combobox-popup role="listbox" hidden tabindex="-1">
      <div data-sw-combobox-empty hidden>No results</div>
      <div data-sw-combobox-list>
        <div data-sw-combobox-item role="option" data-value="astro">
          <span data-sw-combobox-item-text>Astro</span>
          <span data-sw-combobox-item-indicator aria-hidden="true" hidden></span>
        </div>
      </div>
    </div>
  </div>
</div>

const root = document.querySelector("[data-sw-combobox]");
  if (root) {
    createCombobox(root);
  }
</script>
```
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | inputGroup |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, alignOffset, avoidCollisions |
## API Reference
### Root
The main element that owns the Combobox Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Combobox is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | - | control | Sets whether Combobox starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| value | `string \| null` | - | control | Controls the current Combobox value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `string \| null` | - | control | Sets the initial Combobox value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| inputValue | `string` | - | control | Controls the input value for Combobox. | **React:** Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.<br>**Astro:** Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.<br>**Runtime / HTML:** Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates. |
| defaultInputValue | `string` | - | control | Controls the default input value for Combobox. | **React:** Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.<br>**Astro:** Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.<br>**Runtime / HTML:** Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates. |
| autoComplete | `string` | - | option | Sets the native autocomplete behavior. | - |
| disabled | `boolean` | - | option | Disables the Root part. | - |
| filterMode | `"contains" \| "startsWith"` | "contains" | option | Configures the filter mode option for the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| highlightItemOnHover | `boolean` | true | option | Highlights Combobox items when the pointer moves over them. | - |
| locale | `string` | - | option | Sets the locale used by Combobox. | - |
| modal | `boolean` | false | option | Makes Combobox behave as a modal overlay. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| readOnly | `boolean` | false | option | Marks the control as read-only. | - |
| required | `boolean` | - | option | Marks the form control as required. | - |
| onInputValueChange | `(inputValue: string, details: ComboboxInputValueChangeDetails) => void` | - | callback | Runs when on input value change changes for Combobox. | **React:** Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.<br>**Astro:** Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.<br>**Runtime / HTML:** Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates. |
| onOpenChange | `(open: boolean, details: ComboboxOpenChangeDetails) => void` | - | callback | Runs when Combobox opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| onValueChange | `(value: string \| null, details: ComboboxValueChangeDetails) => void` | - | callback | Runs when the Combobox value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Root part. |
| `data-autocomplete` | prop | - | Reflects the autocomplete prop on the Root part. |
| `data-default-input-value` | prop | - | Reflects the default input value prop on the Root part. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-filter-mode` | prop | - | Reflects the filter mode prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-highlight-item-on-hover` | prop | - | Reflects the highlight item on hover prop on the Root part. |
| `data-input-value` | state | - | Reflects the input value state on the Root part. |
| `data-locale` | prop | - | Reflects the locale prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| inputValue | `string` | inputValue | defaultInputValue | `data-default-input-value` | `getInputValue` | `setInputValue` | Tracks the current text input value for Combobox. | **React:** Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.<br>**Astro:** Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.<br>**Runtime / HTML:** Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates. |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Combobox is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| value | `string \| null` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Combobox value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| inputValueChange | onInputValueChange | starwind:input-value-change | inputValue: `string` | ComboboxInputValueChangeDetails | before-state-commit | Yes | Fires when the text input value changes for Combobox. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | ComboboxOpenChangeDetails | before-state-commit | Yes | Fires when Combobox opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| valueChange | onValueChange | starwind:value-change | value: `string \| null` | ComboboxValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Combobox. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setDisabled` | prop: disabled | - | No | Updates whether Combobox is disabled from Runtime code. |
| `setInputValue` | state: inputValue | emit: false, filter: false | Yes | Updates the Combobox text input value from Runtime code. |
| `setOpen` | state: open | - | Yes | Opens or closes Combobox from Runtime code. |
| `setValue` | state: value | - | Yes | Updates the current Combobox value from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Form
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | hiddenInput (hidden) |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Label
Text label associated with Combobox.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |

### Input Group
Groups the input controls for Combobox.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-input-group` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-input-group` | runtime | - | Marks the Input Group part so Starwind Runtime can find it. |

### Input
The native input synchronized by Combobox.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-combobox-input` |
| Role | `combobox` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| input | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `role`, `aria-autocomplete`, `aria-controls`, `aria-expanded`, `autocomplete` | Editable combobox semantics must be available before hydration. |

### Trigger
The control that opens, closes, or targets the Combobox content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-combobox-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |

### Icon
Decorative icon rendered by Combobox.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-combobox-icon` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-icon` | runtime | - | Marks the Icon part so Starwind Runtime can find it. |

### Clear
Clears the current Combobox value.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-combobox-clear` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Clear element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-clear` | runtime | - | Marks the Clear part so Starwind Runtime can find it. |
#### asChild
| Part | Merged Props |
| --- | --- |
| clear | aria, className, data, events, ref |

### Value
Displays the current Combobox value.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-combobox-value` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-value` | runtime | - | Marks the Value part so Starwind Runtime can find it. |

### Hidden Input
The hidden native input synchronized by Combobox.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-combobox-hidden-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-hidden-input` | runtime | - | Marks the Hidden Input part so Starwind Runtime can find it. |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `type`, `form`, `name`, `value`, `aria-hidden`, `tabIndex` | Form value submission must work without waiting for the runtime. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | hiddenInput (hidden) |

### Portal
Moves Combobox overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |

### Positioner
Positions the Combobox content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Combobox content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Combobox content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Combobox content and its trigger. | - |
| alignOffset | `number` | 0 | option | Adjusts the cross-axis alignment offset for Combobox content. | - |
| avoidCollisions | `boolean` | true | option | Allows Combobox content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-align-offset` | prop | - | Reflects the align offset prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |

### Popup
The floating content container for Combobox.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-popup` |
| Role | `listbox` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Combobox content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Combobox content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Combobox content and its trigger. | - |
| alignOffset | `number` | 0 | option | Adjusts the cross-axis alignment offset for Combobox content. | - |
| avoidCollisions | `boolean` | true | option | Allows Combobox content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-align-offset` | prop | - | Reflects the align offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `role`, `hidden`, `data-state`, `data-side`, `data-align` | Floating content starts closed and is positioned by the runtime once opened. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Empty
Content shown when Combobox has no matching items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-empty` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-empty` | runtime | - | Marks the Empty part so Starwind Runtime can find it. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### List
The list of selectable Combobox items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-list` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-list` | runtime | - | Marks the List part so Starwind Runtime can find it. |

### Group
Groups related Combobox items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-group` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-group` | runtime | - | Marks the Group part so Starwind Runtime can find it. |

### Group Label
Labels a group of Combobox items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-group-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-group-label` | runtime | - | Marks the Group Label part so Starwind Runtime can find it. |

### Item
An interactive item inside the Combobox collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-item` |
| Role | `option` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Item part. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |

### Item Text
Text content for a Combobox item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-combobox-item-text` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-item-text` | runtime | - | Marks the Item Text part so Starwind Runtime can find it. |

### Item Indicator
Shows the selected state for a Combobox item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-combobox-item-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-item-indicator` | runtime | - | Marks the Item Indicator part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Item Indicator part. |
| `data-hidden` | state | - | Reflects the hidden state on the Item Indicator part. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Separator
Separates groups of Combobox items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-separator` |
| Role | `separator` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-separator` | runtime | - | Marks the Separator part so Starwind Runtime can find it. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createCombobox`](/docs/runtime/#create-combobox) |
| Import | `@starwind-ui/runtime/combobox` |
| Root part | root |
| Option props | autoComplete, defaultInputValue, defaultOpen, defaultValue, disabled, filterMode, form, highlightItemOnHover, inputValue, locale, modal, name, open, readOnly, required, value |
| Option lifecycles | autoComplete: setter-backed, defaultInputValue: constructor-only, defaultOpen: constructor-only, defaultValue: constructor-only, disabled: setter-backed, filterMode: constructor-only, form: setter-backed, highlightItemOnHover: constructor-only, inputValue: setter-backed, locale: constructor-only, modal: constructor-only, name: setter-backed, open: setter-backed, readOnly: constructor-only, required: setter-backed, value: setter-backed |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | hiddenInput (hidden) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Combobox](/docs/components/combobox/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/combobox` | `createCombobox` |
| Astro Primitive | `@starwind-ui/astro/combobox` | `Combobox`, `ComboboxRoot`, `ComboboxLabel`, `ComboboxInputGroup`, `ComboboxInput`, `ComboboxTrigger`, `ComboboxIcon`, `ComboboxClear`, `ComboboxValue`, `ComboboxPortal`, `ComboboxPositioner`, `ComboboxPopup`, `ComboboxEmpty`, `ComboboxGroup`, `ComboboxGroupLabel`, `ComboboxItem`, `ComboboxItemText`, `ComboboxItemIndicator`, `ComboboxSeparator` |
| React Primitive | `@starwind-ui/react/combobox` | `Combobox`, `ComboboxRoot`, `ComboboxLabel`, `ComboboxInputGroup`, `ComboboxInput`, `ComboboxTrigger`, `ComboboxIcon`, `ComboboxClear`, `ComboboxValue`, `ComboboxPortal`, `ComboboxPositioner`, `ComboboxPopup`, `ComboboxEmpty`, `ComboboxGroup`, `ComboboxGroupLabel`, `ComboboxItem`, `ComboboxItemText`, `ComboboxItemIndicator`, `ComboboxSeparator` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Combobox` |
| runtime-factory | `createCombobox` |
| part | `Combobox.Root` |
| part | `Combobox.Label` |
| part | `Combobox.InputGroup` |
| part | `Combobox.Input` |
| part | `Combobox.Trigger` |
| part | `Combobox.Icon` |
| part | `Combobox.Clear` |
| part | `Combobox.Value` |
| part | `Combobox.Portal` |
| part | `Combobox.Positioner` |
| part | `Combobox.Popup` |
| part | `Combobox.Empty` |
| part | `Combobox.Group` |
| part | `Combobox.GroupLabel` |
| part | `Combobox.Item` |
| part | `Combobox.ItemText` |
| part | `Combobox.ItemIndicator` |
| part | `Combobox.Separator` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
- Preserved cancellation for React Combobox value and input commands.
### v0.1.1
- Added modal background-scroll locking while the combobox popup is open.
### v0.1.0
- Introduced filtering, selection, keyboard navigation, floating-list placement, and form participation.

---

Source: [https://starwind.dev/docs/primitives/context-menu/](https://starwind.dev/docs/primitives/context-menu/) · [Markdown](https://starwind.dev/docs/primitives/context-menu.md)

# Context Menu Primitive

Context Menu is a Starwind Runtime primitive in the composite-menu-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render ContextMenu anatomy with the Runtime wiring included.
```astro
---
import { ContextMenu } from "@starwind-ui/astro/context-menu";
---

<ContextMenu.Root>
  <ContextMenu.Trigger>Right click</ContextMenu.Trigger>
  <ContextMenu.Positioner>
    <ContextMenu.Popup>
      <ContextMenu.Item>Copy</ContextMenu.Item>
    </ContextMenu.Popup>
  </ContextMenu.Positioner>
</ContextMenu.Root>
```

### React
Use the React primitive adapter when ContextMenu state participates in React rendering.
```tsx
import { ContextMenu } from "@starwind-ui/react/context-menu";

export function Example() {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger>Right click</ContextMenu.Trigger>
      <ContextMenu.Positioner>
        <ContextMenu.Popup>
          <ContextMenu.Item>Copy</ContextMenu.Item>
        </ContextMenu.Popup>
      </ContextMenu.Positioner>
    </ContextMenu.Root>
  );
}
```

### HTML
Render the ContextMenu data-sw-* contract yourself, then initialize createContextMenu.
```html
<div data-sw-context-menu data-sw-menu="">
  <div data-sw-context-menu-trigger data-sw-menu-trigger="" aria-haspopup="menu">Right click</div>
  <div data-sw-menu-positioner>
    <div data-sw-menu-popup role="menu" tabindex="-1" hidden>
      <div data-sw-menu-item role="menuitem" tabindex="0">Copy</div>
    </div>
  </div>
</div>

const root = document.querySelector("[data-sw-context-menu]");
  if (root) {
    createContextMenu(root);
  }
</script>
```
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | anchor |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, avoidCollisions |
## API Reference
### Root
The main element that owns the Context Menu Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-context-menu` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Context Menu is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Context Menu starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| modal | `boolean` | true | option | Makes Context Menu behave as a modal overlay. | - |
| closeDelay | `number` | 200 | option | Sets how long Context Menu waits before closing. | - |
| onCloseComplete | `(open: boolean, details: ContextMenuCloseCompleteDetails) => void` | - | callback | Runs after Context Menu has finished closing. | - |
| onOpenChange | `(open: boolean, details: ContextMenuOpenChangeDetails) => void` | - | callback | Runs when Context Menu opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-context-menu` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-sw-menu` | constant | - | Identifies Root metadata for styling and selectors. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Context Menu is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | - | - | Tracks whether Context Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| radioValue | `string` | value | defaultValue | `data-value` | - | - | Tracks the selected radio value for Context Menu. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | ContextMenuOpenChangeDetails | before-state-commit | Yes | Fires when Context Menu opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| closeComplete | onCloseComplete | starwind:close-complete | open: `boolean` | ContextMenuCloseCompleteDetails | after-state-commit | No | Fires after Context Menu has finished closing. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Context Menu from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| context-menu-radio-group | provides | value, defaultValue, onValueChange |
| context-menu-radio-group | consumes | value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-context-menu`, `data-sw-menu`, `data-default-open`, `data-disabled`, `data-modal`, `data-close-delay`, `data-state` | The context menu root needs both context-menu and Menu discovery attributes plus open, disabled, modal, close-delay, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Context Menu content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-context-menu-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Trigger part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-context-menu-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-sw-menu-trigger` | constant | - | Identifies Trigger metadata for styling and selectors. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-context-menu-trigger`, `data-sw-menu-trigger`, `aria-haspopup`, `aria-expanded`, `aria-disabled`, `data-disabled`, `data-state`, `tabindex` | Context menu triggers are focusable trigger regions that provide Menu trigger affordances before pointer, keyboard, and touch listeners attach. |

### Anchor
The virtual anchor used to position Context Menu content.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-context-menu-anchor` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-context-menu-anchor` | runtime | - | Marks the Anchor part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| anchor | No |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-context-menu-anchor`, `style` | The runtime creates a hidden document-positioned anchor at the pointer or keyboard-open position for the shared Menu floating runtime. |

### Portal
Moves Context Menu overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Positioner
Positions the Context Menu content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Context Menu content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Context Menu content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Context Menu content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Context Menu content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Positioner part. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |
#### Refs
| Part | Public |
| --- | --- |
| positioner | Yes |

### Popup
The floating content container for Context Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-popup` |
| Role | `menu` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Context Menu content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Context Menu content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Context Menu content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Context Menu content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-popup`, `role`, `tabindex`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions`, `hidden` | The Menu-backed popup starts hidden and closed with menu semantics and placement hints before runtime positioning. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Item
An interactive item inside the Context Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-item` |
| Role | `menuitem` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Item part. | - |
| closeOnClick | `boolean` | true | option | Closes Context Menu after the item is clicked. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Item part. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |

### Link Item
A link-style item inside the Context Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `a` |
| Discovery hook | `data-sw-menu-link-item` |
| Role | `menuitem` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Link Item part. | - |
| closeOnClick | `boolean` | false | option | Closes Context Menu after the item is clicked. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-link-item` | runtime | - | Marks the Link Item part so Starwind Runtime can find it. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Link Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Link Item part. |
#### Refs
| Part | Public |
| --- | --- |
| linkItem | Yes |

### Checkbox Item
A checkbox-style item inside the Context Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-checkbox-item` |
| Role | `menuitemcheckbox` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Checkbox Item part. | - |
| checked | `boolean` | - | control | Controls whether Context Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| defaultChecked | `boolean` | false | control | Sets whether Context Menu starts checked for uncontrolled usage. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| closeOnClick | `boolean` | false | option | Closes Context Menu after the item is clicked. | - |
| onCheckedChange | `(checked: boolean, details: MenuCheckedChangeDetails) => void` | - | callback | Runs when the Context Menu checked state changes. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-checkbox-item` | runtime | - | Marks the Checkbox Item part so Starwind Runtime can find it. |
| `data-default-checked` | state | - | Reflects the default checked state on the Checkbox Item part. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Checkbox Item part. |
| `data-checked` | state | - | Reflects the checked state on the Checkbox Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Checkbox Item part. |
| `data-unchecked` | state | - | Reflects the unchecked state on the Checkbox Item part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | - | - | Tracks whether Context Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checkedChange | onCheckedChange | starwind:checked-change | checked: `boolean` | MenuCheckedChangeDetails | before-state-commit | Yes | Fires when the checked state changes for Context Menu. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Refs
| Part | Public |
| --- | --- |
| checkboxItem | Yes |

### Checkbox Item Indicator
Shows the checked state for a Context Menu checkbox item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-menu-checkbox-item-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-checkbox-item-indicator` | runtime | - | Marks the Checkbox Item Indicator part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Checkbox Item Indicator part. |
#### Refs
| Part | Public |
| --- | --- |
| checkboxItemIndicator | Yes |

### Radio Group
Groups related radio items inside Context Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-radio-group` |
| Role | `group` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `string` | - | control | Controls the current Context Menu value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
| defaultValue | `string` | - | control | Sets the initial Context Menu value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
| onValueChange | `(value: string, details: MenuValueChangeDetails) => void` | - | callback | Runs when the Context Menu value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-radio-group` | runtime | - | Marks the Radio Group part so Starwind Runtime can find it. |
| `data-value` | state | - | Reflects the value state on the Radio Group part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| radioValue | `string` | value | defaultValue | `data-value` | - | - | Tracks the selected radio value for Context Menu. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `string` | MenuValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Context Menu. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Refs
| Part | Public |
| --- | --- |
| radioGroup | Yes |

### Radio Item
A radio-style item inside the Context Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-radio-item` |
| Role | `menuitemradio` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Radio Item part. | - |
| checked | `boolean` | - | control | Controls whether Context Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| defaultChecked | `boolean` | false | control | Sets whether Context Menu starts checked for uncontrolled usage. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| closeOnClick | `boolean` | false | option | Closes Context Menu after the item is clicked. | - |
| value | `string` | - | option | Controls the current Context Menu value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-radio-item` | runtime | - | Marks the Radio Item part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Radio Item part. |
| `data-default-checked` | state | - | Reflects the default checked state on the Radio Item part. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Radio Item part. |
| `data-checked` | state | - | Reflects the checked state on the Radio Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Radio Item part. |
| `data-unchecked` | state | - | Reflects the unchecked state on the Radio Item part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | - | - | Tracks whether Context Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| radioValue | `string` | value | defaultValue | `data-value` | - | - | Tracks the selected radio value for Context Menu. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Refs
| Part | Public |
| --- | --- |
| radioItem | Yes |

### Radio Item Indicator
Shows the selected state for a Context Menu radio item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-menu-radio-item-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-radio-item-indicator` | runtime | - | Marks the Radio Item Indicator part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Radio Item Indicator part. |
#### Refs
| Part | Public |
| --- | --- |
| radioItemIndicator | Yes |

### Group
Groups related Context Menu items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-group` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-group` | runtime | - | Marks the Group part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| group | Yes |

### Label
Text label associated with Context Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |

### Separator
Separates groups of Context Menu items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-separator` |
| Role | `separator` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-separator` | runtime | - | Marks the Separator part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| separator | Yes |

### Shortcut
Displays keyboard shortcut text for a Context Menu item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-menu-shortcut` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-shortcut` | runtime | - | Marks the Shortcut part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| shortcut | Yes |

### Submenu Root
Owns a nested submenu inside Context Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-submenu-root` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| closeDelay | `number` | 200 | option | Sets how long Context Menu waits before closing. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-submenu-root` | runtime | - | Marks the Submenu Root part so Starwind Runtime can find it. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Submenu Root part. |
| `data-state` | state | - | Reflects the current state on the Submenu Root part. |
#### Refs
| Part | Public |
| --- | --- |
| submenuRoot | Yes |

### Submenu Trigger
Opens a nested submenu inside Context Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-submenu-trigger` |
| Role | `menuitem` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Submenu Trigger part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-submenu-trigger` | runtime | - | Marks the Submenu Trigger part so Starwind Runtime can find it. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Submenu Trigger part. |
| `data-state` | state | - | Reflects the current state on the Submenu Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| submenuTrigger | Yes |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createContextMenu`](/docs/runtime/#create-context-menu) |
| Import | `@starwind-ui/runtime/context-menu` |
| Root part | root |
| Option props | closeDelay, defaultOpen, disabled, modal, onCloseComplete, onOpenChange, open |
| Option lifecycles | closeDelay: constructor-only, defaultOpen: constructor-only, disabled: constructor-only, modal: constructor-only, onCloseComplete: constructor-only, onOpenChange: constructor-only, open: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Context Menu](/docs/components/context-menu/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/context-menu` | `createContextMenu` |
| Astro Primitive | `@starwind-ui/astro/context-menu` | `ContextMenu`, `ContextMenuRoot`, `ContextMenuTrigger`, `ContextMenuPortal`, `ContextMenuPositioner`, `ContextMenuPopup`, `ContextMenuItem`, `ContextMenuLinkItem`, `ContextMenuCheckboxItem`, `ContextMenuCheckboxItemIndicator`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`, `ContextMenuRadioItemIndicator`, `ContextMenuGroup`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuShortcut`, `ContextMenuSubmenuRoot`, `ContextMenuSubmenuTrigger` |
| React Primitive | `@starwind-ui/react/context-menu` | `ContextMenu`, `ContextMenuRoot`, `ContextMenuTrigger`, `ContextMenuPortal`, `ContextMenuPositioner`, `ContextMenuPopup`, `ContextMenuItem`, `ContextMenuLinkItem`, `ContextMenuCheckboxItem`, `ContextMenuCheckboxItemIndicator`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`, `ContextMenuRadioItemIndicator`, `ContextMenuGroup`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuShortcut`, `ContextMenuSubmenuRoot`, `ContextMenuSubmenuTrigger` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `ContextMenu` |
| runtime-factory | `createContextMenu` |
| part | `ContextMenu.Root` |
| part | `ContextMenu.Trigger` |
| part | `ContextMenu.Portal` |
| part | `ContextMenu.Positioner` |
| part | `ContextMenu.Popup` |
| part | `ContextMenu.Item` |
| part | `ContextMenu.LinkItem` |
| part | `ContextMenu.CheckboxItem` |
| part | `ContextMenu.CheckboxItemIndicator` |
| part | `ContextMenu.RadioGroup` |
| part | `ContextMenu.RadioItem` |
| part | `ContextMenu.RadioItemIndicator` |
| part | `ContextMenu.Group` |
| part | `ContextMenu.Label` |
| part | `ContextMenu.Separator` |
| part | `ContextMenu.Shortcut` |
| part | `ContextMenu.SubmenuRoot` |
| part | `ContextMenu.SubmenuTrigger` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.1
- Enabled modal background-scroll locking by default while the menu is open.
### v0.1.0
- Introduced pointer-triggered menus with keyboard navigation, submenus, checked items, and floating placement.

---

Source: [https://starwind.dev/docs/primitives/dialog/](https://starwind.dev/docs/primitives/dialog/) · [Markdown](https://starwind.dev/docs/primitives/dialog.md)

# Dialog Primitive

Dialog is a Starwind Runtime primitive in the dialog-native-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Dialog anatomy with the Runtime wiring included.
```astro
---
import { Dialog } from "@starwind-ui/astro/dialog";
---

<Dialog.Root>
  <Dialog.Trigger>Open dialog</Dialog.Trigger>
  <Dialog.Backdrop />
  <Dialog.Popup>
    <Dialog.Title>Dialog title</Dialog.Title>
    <Dialog.Description>Dialog description</Dialog.Description>
    <Dialog.Close>Close</Dialog.Close>
  </Dialog.Popup>
</Dialog.Root>
```

### React
Use the React primitive adapter when Dialog state participates in React rendering.
```tsx
import { Dialog } from "@starwind-ui/react/dialog";

export function Example() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Open dialog</Dialog.Trigger>
      <Dialog.Backdrop />
      <Dialog.Popup>
        <Dialog.Title>Dialog title</Dialog.Title>
        <Dialog.Description>Dialog description</Dialog.Description>
        <Dialog.Close>Close</Dialog.Close>
      </Dialog.Popup>
    </Dialog.Root>
  );
}
```

### HTML
Render the Dialog data-sw-* contract yourself, then initialize createDialog.
```html
<div data-sw-dialog>
  <button data-sw-dialog-trigger type="button" aria-haspopup="dialog">Open dialog</button>
  <div data-sw-dialog-overlay hidden></div>
  <dialog data-sw-dialog-content role="dialog">
    <h2 data-sw-dialog-title>Dialog title</h2>
    <p data-sw-dialog-description>Dialog description</p>
    <button data-sw-dialog-close type="button">Close</button>
  </dialog>
</div>

const root = document.querySelector("[data-sw-dialog]");
  if (root) {
    createDialog(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Dialog Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-dialog` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Dialog is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Dialog starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| closeOnEscape | `boolean` | true | option | Closes Dialog when Escape is pressed. | - |
| closeOnOutsideInteract | `boolean` | true | option | Closes Dialog when the user interacts outside it. | - |
| modal | `boolean` | true | option | Makes Dialog behave as a modal overlay. | - |
| onCloseComplete | `(open: boolean, details: DialogCloseCompleteDetails) => void` | - | callback | Runs after Dialog has finished closing. | - |
| onOpenChange | `(open: boolean, details: DialogOpenChangeDetails) => void` | - | callback | Runs when Dialog opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dialog` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-close-on-escape` | prop | - | Reflects the close on escape prop on the Root part. |
| `data-close-on-outside-interact` | prop | - | Reflects the close on outside interact prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Dialog is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | DialogOpenChangeDetails | before-state-commit | Yes | Fires when Dialog opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| closeComplete | onCloseComplete | starwind:close-complete | open: `boolean` | DialogCloseCompleteDetails | after-state-commit | No | Fires after Dialog has finished closing. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Dialog from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dialog`, `data-default-open`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-modal`, `data-state` | The dialog root needs default-open, dismissal, modality, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Dialog content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-dialog-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| targetId | `string` | - | attribute | Targets a specific root element by id. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dialog-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-sw-dialog-target-id` | prop | - | Reflects the sw dialog target id prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dialog-trigger`, `type`, `aria-haspopup`, `data-sw-dialog-target-id`, `data-state` | Triggers need button semantics, dialog affordances, and initial closed state before activation listeners attach. |

### Backdrop
The backdrop shown behind the Dialog overlay.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-dialog-overlay` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dialog-overlay` | runtime | - | Marks the Backdrop part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Backdrop part. |
#### Refs
| Part | Public |
| --- | --- |
| backdrop | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dialog-overlay`, `data-state`, `hidden` | The backdrop starts hidden and receives runtime-owned open/close visibility. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Popup
The floating content container for Dialog.
| Fact | Value |
| --- | --- |
| Default element | `dialog` |
| Discovery hook | `data-sw-dialog-content` |
| Role | `dialog` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dialog-content` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dialog-content`, `data-state` | The native dialog element starts closed and receives runtime-owned open/close state. |

### Title
The accessible title for Dialog.
| Fact | Value |
| --- | --- |
| Default element | `h2` |
| Discovery hook | `data-sw-dialog-title` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dialog-title` | runtime | - | Marks the Title part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| title | Yes |

### Description
Supporting description text for Dialog.
| Fact | Value |
| --- | --- |
| Default element | `p` |
| Discovery hook | `data-sw-dialog-description` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dialog-description` | runtime | - | Marks the Description part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| description | Yes |

### Close
A control that closes Dialog.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-dialog-close` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dialog-close` | runtime | - | Marks the Close part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| close | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dialog-close`, `type` | Close controls need button semantics before runtime listeners attach. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createDialog`](/docs/runtime/#create-dialog) |
| Import | `@starwind-ui/runtime/dialog` |
| Root part | root |
| Option props | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open |
| Option lifecycles | closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultOpen: constructor-only, modal: constructor-only, onCloseComplete: constructor-only, onOpenChange: constructor-only, open: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Dialog](/docs/components/dialog/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/dialog` | `createDialog` |
| Astro Primitive | `@starwind-ui/astro/dialog` | `Dialog`, `DialogRoot`, `DialogTrigger`, `DialogBackdrop`, `DialogPopup`, `DialogTitle`, `DialogDescription`, `DialogClose` |
| React Primitive | `@starwind-ui/react/dialog` | `Dialog`, `DialogRoot`, `DialogTrigger`, `DialogBackdrop`, `DialogPopup`, `DialogTitle`, `DialogDescription`, `DialogClose` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Dialog` |
| runtime-factory | `createDialog` |
| part | `Dialog.Root` |
| part | `Dialog.Trigger` |
| part | `Dialog.Backdrop` |
| part | `Dialog.Popup` |
| part | `Dialog.Title` |
| part | `Dialog.Description` |
| part | `Dialog.Close` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced modal and non-modal open state, focus management, dismissal, presence, and nested-dialog coordination.

---

Source: [https://starwind.dev/docs/primitives/drawer/](https://starwind.dev/docs/primitives/drawer/) · [Markdown](https://starwind.dev/docs/primitives/drawer.md)

# Drawer Primitive

Drawer is a Starwind Runtime primitive in the dialog-native-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Drawer anatomy with the Runtime wiring included.
```astro
---
import { Drawer } from "@starwind-ui/astro/drawer";
---

<Drawer.Root>
  <Drawer.Trigger>Open drawer</Drawer.Trigger>
  <Drawer.Backdrop />
  <Drawer.Viewport>
    <Drawer.Popup>
      <Drawer.Title>Drawer title</Drawer.Title>
      <Drawer.Description>Drawer description</Drawer.Description>
      <Drawer.Close>Close</Drawer.Close>
    </Drawer.Popup>
  </Drawer.Viewport>
</Drawer.Root>
```

### React
Use the React primitive adapter when Drawer state participates in React rendering.
```tsx
import { Drawer } from "@starwind-ui/react/drawer";

export function Example() {
  return (
    <Drawer.Root>
      <Drawer.Trigger>Open drawer</Drawer.Trigger>
      <Drawer.Backdrop />
      <Drawer.Viewport>
        <Drawer.Popup>
          <Drawer.Title>Drawer title</Drawer.Title>
          <Drawer.Description>Drawer description</Drawer.Description>
          <Drawer.Close>Close</Drawer.Close>
        </Drawer.Popup>
      </Drawer.Viewport>
    </Drawer.Root>
  );
}
```

### HTML
Render the Drawer data-sw-* contract yourself, then initialize createDrawer.
```html
<div data-sw-drawer>
  <button data-sw-drawer-trigger type="button" aria-haspopup="dialog">Open drawer</button>
  <div data-sw-drawer-backdrop hidden></div>
  <div data-sw-drawer-viewport>
    <dialog data-sw-drawer-popup role="dialog">
      <h2 data-sw-drawer-title>Drawer title</h2>
      <p data-sw-drawer-description>Drawer description</p>
      <button data-sw-drawer-close type="button">Close</button>
    </dialog>
  </div>
</div>

const root = document.querySelector("[data-sw-drawer]");
  if (root) {
    createDrawer(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Drawer Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-drawer` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Drawer is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Drawer starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| closeOnEscape | `boolean` | true | option | Closes Drawer when Escape is pressed. | - |
| closeOnOutsideInteract | `boolean` | true | option | Closes Drawer when the user interacts outside it. | - |
| modal | `boolean` | true | option | Makes Drawer behave as a modal overlay. | - |
| onCloseComplete | `(open: boolean, details: DrawerCloseCompleteDetails) => void` | - | callback | Runs after Drawer has finished closing. | - |
| onOpenChange | `(open: boolean, details: DrawerOpenChangeDetails) => void` | - | callback | Runs when Drawer opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-close-on-escape` | prop | - | Reflects the close on escape prop on the Root part. |
| `data-close-on-outside-interact` | prop | - | Reflects the close on outside interact prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Drawer is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | DrawerOpenChangeDetails | before-state-commit | Yes | Fires when Drawer opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| closeComplete | onCloseComplete | starwind:close-complete | open: `boolean` | DrawerCloseCompleteDetails | after-state-commit | No | Fires after Drawer has finished closing. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Drawer from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-drawer`, `data-default-open`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-modal`, `data-state` | The drawer root needs default-open, dismissal, modality, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Drawer content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-drawer-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| targetId | `string` | - | attribute | Targets a specific root element by id. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-sw-drawer-target-id` | prop | - | Reflects the sw drawer target id prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-drawer-trigger`, `type`, `aria-haspopup`, `data-sw-drawer-target-id`, `data-state` | Triggers need button semantics, dialog affordances, and initial closed state before activation listeners attach. |

### Portal
Moves Drawer overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-drawer-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Backdrop
The backdrop shown behind the Drawer overlay.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-drawer-backdrop` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-backdrop` | runtime | - | Marks the Backdrop part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Backdrop part. |
#### Refs
| Part | Public |
| --- | --- |
| backdrop | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-drawer-backdrop`, `data-state`, `hidden` | The backdrop starts hidden and receives runtime-owned open/close visibility. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Viewport
The visible viewport for Drawer content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-drawer-viewport` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |

### Popup
The floating content container for Drawer.
| Fact | Value |
| --- | --- |
| Default element | `dialog` |
| Discovery hook | `data-sw-drawer-popup` |
| Role | `dialog` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "right" | option | Sets the preferred side for Drawer content. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-drawer-popup`, `data-state`, `data-side` | The native drawer popup starts closed with dialog semantics and side placement before runtime normalization maps it onto the Dialog controller. |

### Title
The accessible title for Drawer.
| Fact | Value |
| --- | --- |
| Default element | `h2` |
| Discovery hook | `data-sw-drawer-title` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-title` | runtime | - | Marks the Title part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| title | Yes |

### Description
Supporting description text for Drawer.
| Fact | Value |
| --- | --- |
| Default element | `p` |
| Discovery hook | `data-sw-drawer-description` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-description` | runtime | - | Marks the Description part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| description | Yes |

### Close
A control that closes Drawer.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-drawer-close` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-close` | runtime | - | Marks the Close part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| close | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-drawer-close`, `type` | Close controls need button semantics before runtime listeners attach. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createDrawer`](/docs/runtime/#create-drawer) |
| Import | `@starwind-ui/runtime/drawer` |
| Root part | root |
| Option props | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open |
| Option lifecycles | closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultOpen: constructor-only, modal: constructor-only, onCloseComplete: constructor-only, onOpenChange: constructor-only, open: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Sheet](/docs/components/sheet/) | Renamed Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/drawer` | `createDrawer` |
| Astro Primitive | `@starwind-ui/astro/drawer` | `Drawer`, `DrawerRoot`, `DrawerTrigger`, `DrawerPortal`, `DrawerBackdrop`, `DrawerViewport`, `DrawerPopup`, `DrawerTitle`, `DrawerDescription`, `DrawerClose` |
| React Primitive | `@starwind-ui/react/drawer` | `Drawer`, `DrawerRoot`, `DrawerTrigger`, `DrawerPortal`, `DrawerBackdrop`, `DrawerViewport`, `DrawerPopup`, `DrawerTitle`, `DrawerDescription`, `DrawerClose` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Drawer` |
| runtime-factory | `createDrawer` |
| part | `Drawer.Root` |
| part | `Drawer.Trigger` |
| part | `Drawer.Portal` |
| part | `Drawer.Backdrop` |
| part | `Drawer.Viewport` |
| part | `Drawer.Popup` |
| part | `Drawer.Title` |
| part | `Drawer.Description` |
| part | `Drawer.Close` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced sliding dialog behavior with modal state, focus management, dismissal, and panel presence.

---

Source: [https://starwind.dev/docs/primitives/dropzone/](https://starwind.dev/docs/primitives/dropzone/) · [Markdown](https://starwind.dev/docs/primitives/dropzone.md)

# Dropzone Primitive

Dropzone is a Starwind Runtime primitive in the form-value-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Dropzone anatomy with the Runtime wiring included.
```astro
---
import { Dropzone } from "@starwind-ui/astro/dropzone";
---

<Dropzone.Root>
  <Dropzone.Input />
  <Dropzone.UploadIndicator>Drop files here</Dropzone.UploadIndicator>
  <Dropzone.LoadingIndicator>Uploading...</Dropzone.LoadingIndicator>
  <Dropzone.FilesList />
</Dropzone.Root>
```

### React
Use the React primitive adapter when Dropzone state participates in React rendering.
```tsx
import { Dropzone } from "@starwind-ui/react/dropzone";

export function Example() {
  return (
    <Dropzone.Root>
      <Dropzone.Input />
      <Dropzone.UploadIndicator>Drop files here</Dropzone.UploadIndicator>
      <Dropzone.LoadingIndicator>Uploading...</Dropzone.LoadingIndicator>
      <Dropzone.FilesList />
    </Dropzone.Root>
  );
}
```

### HTML
Render the Dropzone data-sw-* contract yourself, then initialize createDropzone.
```html
<label data-sw-dropzone role="button">
  <input data-sw-dropzone-input type="file" tabindex="-1" class="sr-only" />
  <div data-sw-dropzone-upload-indicator>Drop files here</div>
  <div data-sw-dropzone-loading-indicator hidden>Uploading...</div>
  <div data-sw-dropzone-files-list></div>
</label>

const root = document.querySelector("[data-sw-dropzone]");
  if (root) {
    createDropzone(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Dropzone Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `label` |
| Discovery hook | `data-sw-dropzone` |
| Role | `button` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| isUploading | `boolean` | false | control | Controls whether Dropzone is uploading. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
| onFilesChange | `(files: File[], details: DropzoneFilesChangeDetails) => void` | - | callback | Runs when selected files change for Dropzone. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dropzone` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-drag-active` | state | - | Reflects the drag active state on the Root part. |
| `data-has-files` | state | - | Reflects the has files state on the Root part. |
| `data-is-uploading` | prop | - | Reflects the uploading prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| uploading | `boolean` | isUploading | - | `data-is-uploading` | `getUploading` | `setUploading` | Tracks whether Dropzone is uploading files. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| filesChange | onFilesChange | starwind:files-change | files: `File[]` | DropzoneFilesChangeDetails | - | - | Fires when selected files change for Dropzone. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setDisabled` | prop: disabled | - | No | Updates whether Dropzone is disabled from Runtime code. |
| `setUploading` | prop: isUploading | - | No | Updates whether Dropzone is uploading files from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dropzone`, `data-disabled`, `data-drag-active`, `data-has-files`, `data-is-uploading`, `aria-disabled`, `role`, `tabindex` | The visible drop target needs button semantics, disabled state, drag state, file presence, and upload state before hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | accept, multiple, name, required |
| Hidden input | input (file) |

### Input
The native input synchronized by Dropzone.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-dropzone-input` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| accept | `string` | - | attribute | Limits which file types can be selected. | - |
| multiple | `boolean` | - | attribute | Allows multiple Dropzone values to be selected. | - |
| name | `string` | - | attribute | Sets the submitted form field name. | - |
| required | `boolean` | - | attribute | Marks the form control as required. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dropzone-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Input part. |
#### Refs
| Part | Public |
| --- | --- |
| input | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dropzone-input`, `type`, `tabindex`, `class`, `data-disabled`, `disabled` | The native file input must be present for form compatibility while remaining visually hidden and out of the tab order. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | accept, multiple, name, required |
| Hidden input | input (file) |

### Upload Indicator
Upload progress indicator shown by Dropzone.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-dropzone-upload-indicator` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| isUploading | `boolean` | false | control | Controls whether Dropzone is uploading. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dropzone-upload-indicator` | runtime | - | Marks the Upload Indicator part so Starwind Runtime can find it. |
| `data-is-uploading` | state | - | Reflects the uploading state on the Upload Indicator part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| uploading | `boolean` | isUploading | - | `data-is-uploading` | `getUploading` | `setUploading` | Tracks whether Dropzone is uploading files. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
#### Refs
| Part | Public |
| --- | --- |
| uploadIndicator | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dropzone-upload-indicator`, `data-is-uploading` | The upload indicator reflects the initial uploading state before the runtime attaches. |

### Loading Indicator
Loading indicator shown by Dropzone.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-dropzone-loading-indicator` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| isUploading | `boolean` | false | control | Controls whether Dropzone is uploading. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dropzone-loading-indicator` | runtime | - | Marks the Loading Indicator part so Starwind Runtime can find it. |
| `data-is-uploading` | state | - | Reflects the uploading state on the Loading Indicator part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| uploading | `boolean` | isUploading | - | `data-is-uploading` | `getUploading` | `setUploading` | Tracks whether Dropzone is uploading files. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
#### Refs
| Part | Public |
| --- | --- |
| loadingIndicator | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dropzone-loading-indicator`, `data-is-uploading`, `hidden` | The loading indicator starts hidden unless the dropzone is already uploading. |

### Files List
Lists the selected files for Dropzone.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-dropzone-files-list` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dropzone-files-list` | runtime | - | Marks the Files List part so Starwind Runtime can find it. |
| `data-has-files` | state | - | Reflects the has files state on the Files List part. |
#### Refs
| Part | Public |
| --- | --- |
| filesList | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dropzone-files-list`, `data-has-files` | The files list starts empty and receives file presence state from the runtime. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createDropzone`](/docs/runtime/#create-dropzone) |
| Import | `@starwind-ui/runtime/dropzone` |
| Root part | root |
| Option props | disabled, isUploading, onFilesChange |
| Option lifecycles | disabled: setter-backed, isUploading: setter-backed, onFilesChange: constructor-only |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | accept, multiple, name, required |
| Hidden input | input (file) |
| Field integration | No |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Dropzone](/docs/components/dropzone/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/dropzone` | `createDropzone` |
| Astro Primitive | `@starwind-ui/astro/dropzone` | `Dropzone`, `DropzoneRoot`, `DropzoneInput`, `DropzoneUploadIndicator`, `DropzoneLoadingIndicator`, `DropzoneFilesList` |
| React Primitive | `@starwind-ui/react/dropzone` | `Dropzone`, `DropzoneRoot`, `DropzoneInput`, `DropzoneUploadIndicator`, `DropzoneLoadingIndicator`, `DropzoneFilesList` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Dropzone` |
| runtime-factory | `createDropzone` |
| part | `Dropzone.Root` |
| part | `Dropzone.Input` |
| part | `Dropzone.UploadIndicator` |
| part | `Dropzone.LoadingIndicator` |
| part | `Dropzone.FilesList` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced drag-and-drop state, file-input coordination, acceptance checks, and file-change events.

---

Source: [https://starwind.dev/docs/primitives/field/](https://starwind.dev/docs/primitives/field/) · [Markdown](https://starwind.dev/docs/primitives/field.md)

# Field Primitive

Field is a Starwind Runtime primitive in the field-control-coordinator contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Field anatomy with the Runtime wiring included.
```astro
---
import { Field } from "@starwind-ui/astro/field";
---

<Field.Root>
  <Field.Label>Email</Field.Label>
  <Field.Control />
  <Field.Description>Use your work email.</Field.Description>
  <Field.Error>Enter a valid email.</Field.Error>
</Field.Root>
```

### React
Use the React primitive adapter when Field state participates in React rendering.
```tsx
import { Field } from "@starwind-ui/react/field";

export function Example() {
  return (
    <Field.Root>
      <Field.Label>Email</Field.Label>
      <Field.Control />
      <Field.Description>Use your work email.</Field.Description>
      <Field.Error>Enter a valid email.</Field.Error>
    </Field.Root>
  );
}
```

### HTML
Render the Field data-sw-* contract yourself, then initialize createField.
```html
<div data-sw-field>
  <label data-sw-field-label>Email</label>
  <input data-sw-field-control data-sw-input />
  <p data-sw-field-description>Use your work email.</p>
  <div data-sw-field-error hidden>Enter a valid email.</div>
</div>

const root = document.querySelector("[data-sw-field]");
  if (root) {
    createField(root);
  }
</script>
```
## Validation policy values
The timing props accept semantic `change`, `blur`, `submit`, or `manual` causes. Field values override the owning Form; otherwise they inherit its submit/change/submit defaults and post-submit replacement policy.
## API Reference
### Root
The main element that owns the Field Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-field` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| dirty | `boolean` | - | control | Marks whether the field value has changed. | **React:** Use dirty for controlled state.<br>**Astro:** Use dirty for initial state and call setDirty for later updates.<br>**Runtime / HTML:** call setDirty for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| data-error-visibility | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level errorVisibility form for semantic change, blur, submit, or manual validation; overrides the owning Form for this Field. | - |
| data-revalidation-timing | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level revalidationTiming form that replaces validationTiming after a submission attempt; overrides the owning Form for this Field. | - |
| data-validation-timing | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level validationTiming form for semantic change, blur, submit, or manual validation before submission; overrides the owning Form for this Field. | - |
| errorVisibility | `"blur" \| "change" \| "manual" \| "submit"` | submit | option | Selects whether semantic change, blur, submit, or manual validation reveals this Field's errors; inherits the owning Form policy when omitted. | - |
| invalid | `boolean` | - | control | Marks the field as invalid for validation styling and state. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| revalidationTiming | `"blur" \| "change" \| "manual" \| "submit"` | change | option | After an owning Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; inherits the owning Form policy when omitted. | - |
| touched | `boolean` | - | control | Marks whether the field has been visited. | **React:** Use touched for controlled state.<br>**Astro:** Use touched for initial state and call setTouched for later updates.<br>**Runtime / HTML:** call setTouched for later updates. |
| validationTiming | `"blur" \| "change" \| "manual" \| "submit"` | submit | option | Selects semantic change, blur, submit, or manual validation before an owning Form submission attempt; inherits the owning Form policy when omitted. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-dirty` | state | - | Reflects the dirty state on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-error-visibility` | prop | - | Reflects the error visibility prop on the Root part. |
| `data-invalid` | state | - | Reflects the invalid state on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-revalidation-timing` | prop | - | Reflects the revalidation timing prop on the Root part. |
| `data-touched` | state | - | Reflects the touched state on the Root part. |
| `data-validation-timing` | prop | - | Reflects the validation timing prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| dirty | `boolean` | dirty | - | - | - | `setDirty` | Tracks whether the Field value has changed. | **React:** Use dirty for controlled state.<br>**Astro:** Use dirty for initial state and call setDirty for later updates.<br>**Runtime / HTML:** call setDirty for later updates. |
| touched | `boolean` | touched | - | - | - | `setTouched` | Tracks whether Field has been visited. | **React:** Use touched for controlled state.<br>**Astro:** Use touched for initial state and call setTouched for later updates.<br>**Runtime / HTML:** call setTouched for later updates. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setDirty` | prop: dirty | - | No | Updates whether Field is dirty from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Field is disabled from Runtime code. |
| `setInvalid` | prop: invalid | - | No | Updates whether Field is invalid from Runtime code. |
| `setName` | prop: name | - | No | Updates the Field form field name from Runtime code. |
| `setTouched` | prop: touched | - | No | Updates whether Field is touched from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-field`, `data-dirty`, `data-disabled`, `data-error-visibility`, `data-invalid`, `data-name`, `data-revalidation-timing`, `data-touched`, `data-validation-timing` | Field-owned control state must be available for styling and ownership before the controller attaches. |

### Label
Text label associated with Field.
| Fact | Value |
| --- | --- |
| Default element | `label` |
| Discovery hook | `data-sw-field-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |

### Control
Groups the interactive controls for Field.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-field-control` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-control` | runtime | - | Marks the Control part so Starwind Runtime can find it. |
| `data-sw-input` | constant | - | Identifies Control metadata for styling and selectors. |
#### Refs
| Part | Public |
| --- | --- |
| control | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-field-control`, `data-sw-input` | The generated default Field control must be discoverable as both a Field control and an Input primitive. |

### Description
Supporting description text for Field.
| Fact | Value |
| --- | --- |
| Default element | `p` |
| Discovery hook | `data-sw-field-description` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-description` | runtime | - | Marks the Description part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| description | Yes |

### Item
An interactive item inside the Field collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-field-item` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |

### Error
Error message content for Field.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-field-error` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| match | `FieldErrorMatch` | false | attribute | Controls how Field filters matching items. | - |
| messageSource | `"children" \| "validation"` | - | attribute | Sets the message source attribute on the Error part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-error` | runtime | - | Marks the Error part so Starwind Runtime can find it. |
| `data-match` | prop | - | Reflects the match prop on the Error part. |
| `data-message-source` | prop | - | Reflects the message source prop on the Error part. |
#### Refs
| Part | Public |
| --- | --- |
| error | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-field-error`, `data-match`, `data-message-source`, `hidden` | Validation messaging starts hidden and is revealed by the Field controller. |

### Validity
Validation state container for Field.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-field-validity` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| match | `FieldErrorMatch` | true | attribute | Controls how Field filters matching items. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-validity` | runtime | - | Marks the Validity part so Starwind Runtime can find it. |
| `data-match` | prop | - | Reflects the match prop on the Validity part. |
#### Refs
| Part | Public |
| --- | --- |
| validity | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-field-validity`, `data-match`, `hidden` | Validity messaging starts hidden and is revealed by the Field controller. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createField`](/docs/runtime/#create-field) |
| Import | `@starwind-ui/runtime/field` |
| Root part | root |
| Option props | dirty, disabled, invalid, name, touched |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Field](/docs/components/field/) | Composite |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/field` | `createField` |
| Astro Primitive | `@starwind-ui/astro/field` | `Field`, `FieldRoot`, `FieldLabel`, `FieldControl`, `FieldDescription`, `FieldItem`, `FieldError`, `FieldValidity` |
| React Primitive | `@starwind-ui/react/field` | `Field`, `FieldRoot`, `FieldLabel`, `FieldControl`, `FieldDescription`, `FieldItem`, `FieldError`, `FieldValidity` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Field` |
| runtime-factory | `createField` |
| part | `Field.Root` |
| part | `Field.Label` |
| part | `Field.Control` |
| part | `Field.Description` |
| part | `Field.Item` |
| part | `Field.Error` |
| part | `Field.Validity` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced field labels, descriptions, validation state, and accessible message coordination.

---

Source: [https://starwind.dev/docs/primitives/fieldset/](https://starwind.dev/docs/primitives/fieldset/) · [Markdown](https://starwind.dev/docs/primitives/fieldset.md)

# Fieldset Primitive

Fieldset is a Starwind Runtime primitive in the field-control-coordinator contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Fieldset anatomy with the Runtime wiring included.
```astro
---
import { Fieldset } from "@starwind-ui/astro/fieldset";
---

<Fieldset.Root>
  <Fieldset.Legend>Preferences</Fieldset.Legend>
</Fieldset.Root>
```

### React
Use the React primitive adapter when Fieldset state participates in React rendering.
```tsx
import { Fieldset } from "@starwind-ui/react/fieldset";

export function Example() {
  return (
    <Fieldset.Root>
      <Fieldset.Legend>Preferences</Fieldset.Legend>
    </Fieldset.Root>
  );
}
```

### HTML
Render the Fieldset data-sw-* contract yourself, then initialize createFieldset.
```html
<fieldset data-sw-fieldset>
  <div data-sw-fieldset-legend>Preferences</div>
</fieldset>

const root = document.querySelector("[data-sw-fieldset]");
  if (root) {
    createFieldset(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Fieldset Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `fieldset` |
| Discovery hook | `data-sw-fieldset` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Root part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-fieldset` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setDisabled` | prop: disabled | - | No | Updates whether Fieldset is disabled from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-fieldset`, `data-disabled` | Fieldsets must expose disabled grouping state before initialization so child Fields can inherit it. |

### Legend
Legend text for the Fieldset fieldset.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-fieldset-legend` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-fieldset-legend` | runtime | - | Marks the Legend part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| legend | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-fieldset-legend` | The Fieldset controller associates legend ids with the root and then mirrors disabled state for styling. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createFieldset`](/docs/runtime/#create-fieldset) |
| Import | `@starwind-ui/runtime/fieldset` |
| Root part | root |
| Option props | disabled |
| Option lifecycles | disabled: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Field](/docs/components/field/) | Composite |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/fieldset` | `createFieldset` |
| Astro Primitive | `@starwind-ui/astro/fieldset` | `Fieldset`, `FieldsetRoot`, `FieldsetLegend` |
| React Primitive | `@starwind-ui/react/fieldset` | `Fieldset`, `FieldsetRoot`, `FieldsetLegend` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Fieldset` |
| runtime-factory | `createFieldset` |
| part | `Fieldset.Root` |
| part | `Fieldset.Legend` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced grouped field state with legend, disabled, invalid, and accessible description coordination.

---

Source: [https://starwind.dev/docs/primitives/form/](https://starwind.dev/docs/primitives/form/) · [Markdown](https://starwind.dev/docs/primitives/form.md)

# Form Primitive

Form coordinates native constraints, custom and asynchronous validators, schema results, error visibility, and submission across its Fields.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Form anatomy with the Runtime wiring included.
```astro
---
import { Form } from "@starwind-ui/astro/form";
---

<Form.Root>
  <Form.ErrorSummary>Please fix the highlighted fields.</Form.ErrorSummary>
</Form.Root>
```

### React
Use the React primitive adapter when Form state participates in React rendering.
```tsx
import { Form } from "@starwind-ui/react/form";

export function Example() {
  return (
    <Form.Root>
      <Form.ErrorSummary>Please fix the highlighted fields.</Form.ErrorSummary>
    </Form.Root>
  );
}
```

### HTML
Render the Form data-sw-* contract yourself, then initialize createForm.
```html
<form data-sw-form data-slot="form">
  <div data-sw-form-error-summary data-slot="form-error-summary" role="status" aria-live="polite" aria-atomic="true" hidden>Please fix the highlighted fields.</div>
</form>

const root = document.querySelector("[data-sw-form]");
  if (root) {
    createForm(root);
  }
</script>
```
## Validation policy values
`validationTiming`, `revalidationTiming`, and `errorVisibility` accept semantic `change`, `blur`, `submit`, or `manual` causes. `change` means each accepted value revision for native and Runtime controls. Before submission, only `validationTiming` is active; after a submission attempt, `revalidationTiming` replaces it. The defaults are `validationTiming="submit"`, `revalidationTiming="change"`, and `errorVisibility="submit"`.
## API Reference
### Root
The main element that owns the Form Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `form` |
| Discovery hook | `data-sw-form` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| data-error-visibility | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level errorVisibility form for semantic change, blur, submit, or manual validation; defaults to submit. | - |
| data-revalidation-timing | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level revalidationTiming form that replaces validationTiming after a submission attempt; defaults to change. | - |
| data-validation-timing | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level validationTiming form for semantic change, blur, submit, or manual validation before submission; defaults to submit. | - |
| errorVisibility | `"blur" \| "change" \| "manual" \| "submit"` | submit | option | Selects whether semantic change, blur, submit, or manual validation reveals errors; defaults to submit. | - |
| revalidationTiming | `"blur" \| "change" \| "manual" \| "submit"` | change | option | After a Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; defaults to change. | - |
| validationTiming | `"blur" \| "change" \| "manual" \| "submit"` | submit | option | Selects semantic change, blur, submit, or manual validation before a Form submission attempt; defaults to submit. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-form` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-slot` | constant | `form` | Identifies Root metadata for styling and selectors. |
| `data-error-visibility` | prop | - | Reflects the error visibility prop on the Root part. |
| `data-revalidation-timing` | prop | - | Reflects the revalidation timing prop on the Root part. |
| `data-validation-timing` | prop | - | Reflects the validation timing prop on the Root part. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-form`, `data-slot`, `data-error-visibility`, `data-revalidation-timing`, `data-validation-timing` | Form must be discoverable before initialization so it can register nested Fields and preserve native form behavior. |

### Error Summary
Summary of validation errors for Form.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-form-error-summary` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-form-error-summary` | runtime | - | Marks the Error Summary part so Starwind Runtime can find it. |
| `data-slot` | constant | `form-error-summary` | Identifies Error Summary metadata for styling and selectors. |
#### Refs
| Part | Public |
| --- | --- |
| error-summary | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-form-error-summary`, `data-slot`, `role`, `aria-live`, `aria-atomic`, `hidden` | Form error summaries start hidden, expose a public part identity, and provide a polite accessible live region before the runtime renders visible errors. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createForm`](/docs/runtime/#create-form) |
| Import | `@starwind-ui/runtime/form` |
| Root part | root |
| Option props | - |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Form](/docs/components/form/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/form` | `createForm` |
| Astro Primitive | `@starwind-ui/astro/form` | `Form`, `FormRoot`, `FormErrorSummary` |
| React Primitive | `@starwind-ui/react/form` | `Form`, `FormRoot`, `FormErrorSummary` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Form` |
| runtime-factory | `createForm` |
| part | `Form.Root` |
| part | `Form.ErrorSummary` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.2.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.2.0
- Replaced additive validation timing with before- and after-submit policies and added imperative validation, visibility, reset, and external-error APIs.
- Unified the previous input and committed-only change timings as change, which now runs for every accepted value revision.
### v0.1.0
- Introduced native form coordination, validation timing, submission state, and field reset behavior.

---

Source: [https://starwind.dev/docs/primitives/input/](https://starwind.dev/docs/primitives/input/) · [Markdown](https://starwind.dev/docs/primitives/input.md)

# Input Primitive

Input is a Starwind Runtime primitive in the form-value-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Input anatomy with the Runtime wiring included.
```astro
---
import { Input } from "@starwind-ui/astro/input";
---

<Input.Root placeholder="Email" />
```

### React
Use the React primitive adapter when Input state participates in React rendering.
```tsx
import { Input } from "@starwind-ui/react/input";

export function Example() {
  return (
    <Input.Root placeholder="Email" />
  );
}
```

### HTML
Render the Input data-sw-* contract yourself, then initialize createInput.
```html
<input data-sw-input placeholder="Email" />

const root = document.querySelector("[data-sw-input]");
  if (root) {
    createInput(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Input Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-input` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `InputValue` | - | control | Controls the current Input value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for state changes.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** listen for starwind:value-change and call setValue for later updates. |
| defaultValue | `InputValue` | - | control | Sets the initial Input value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for state changes.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** listen for starwind:value-change and call setValue for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| name | `string` | - | attribute | Sets the submitted form field name. | - |
| required | `boolean` | - | attribute | Marks the form control as required. | - |
| onValueChange | `(value: string, details: InputValueChangeDetails) => void` | - | callback | Runs when the Input value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for state changes.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** listen for starwind:value-change and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-input` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `InputValue` | value | defaultValue | - | `getValue` | `setValue` | Tracks the current Input value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for state changes.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** listen for starwind:value-change and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `string` | InputValueChangeDetails | - | - | Fires when the value changes for Input. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Input value from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Input is disabled from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-input`, `data-disabled`, `disabled`, `value` | The native input must participate in forms and expose disabled/value state before the controller attaches. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | name, required, value |
| Hidden input | - |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createInput`](/docs/runtime/#create-input) |
| Import | `@starwind-ui/runtime/input` |
| Root part | root |
| Option props | defaultValue, disabled, onValueChange, value |
| Option lifecycles | - |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | name, required, value |
| Hidden input | - |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Input](/docs/components/input/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/input` | `createInput` |
| Astro Primitive | `@starwind-ui/astro/input` | `Input`, `InputRoot` |
| React Primitive | `@starwind-ui/react/input` | `Input`, `InputRoot` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Input` |
| runtime-factory | `createInput` |
| part | `Input.Root` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced value synchronization and Runtime state while preserving native input attributes and events.

---

Source: [https://starwind.dev/docs/primitives/input-otp/](https://starwind.dev/docs/primitives/input-otp/) · [Markdown](https://starwind.dev/docs/primitives/input-otp.md)

# Input OTP Primitive

Input OTP is a Starwind Runtime primitive in the form-value-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render InputOtp anatomy with the Runtime wiring included.
```astro
---
import { InputOtp } from "@starwind-ui/astro/input-otp";
---

<InputOtp.Root>
  <InputOtp.Group>
    <InputOtp.Slot index={0} />
    <InputOtp.Separator />
    <InputOtp.Slot index={1} />
  </InputOtp.Group>
</InputOtp.Root>
```

### React
Use the React primitive adapter when InputOtp state participates in React rendering.
```tsx
import { InputOtp } from "@starwind-ui/react/input-otp";

export function Example() {
  return (
    <InputOtp.Root>
      <InputOtp.Group>
        <InputOtp.Slot index={0} />
        <InputOtp.Separator />
        <InputOtp.Slot index={1} />
      </InputOtp.Group>
    </InputOtp.Root>
  );
}
```

### HTML
Render the InputOtp data-sw-* contract yourself, then initialize createInputOtp.
```html
<div data-sw-input-otp>
  <input data-sw-input-otp-input autocomplete="one-time-code" class="sr-only" tabindex="-1" />
  <div data-sw-input-otp-group>
    <div data-sw-input-otp-slot data-index="0">
      <span data-sw-input-otp-char></span>
      <div data-sw-input-otp-caret class="pointer-events-none absolute inset-0 hidden items-center justify-center" hidden></div>
    </div>
    <div data-sw-input-otp-separator role="separator" aria-hidden="true"></div>
    <div data-sw-input-otp-slot data-index="1">
      <span data-sw-input-otp-char></span>
      <div data-sw-input-otp-caret class="pointer-events-none absolute inset-0 hidden items-center justify-center" hidden></div>
    </div>
  </div>
</div>

const root = document.querySelector("[data-sw-input-otp]");
  if (root) {
    createInputOtp(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Input OTP Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-input-otp` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `string` | - | control | Controls the current Input OTP value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `string` | - | control | Sets the initial Input OTP value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| id | `string` | - | option | Sets the id used by the associated native control. | - |
| maxLength | `number` | 6 | option | Configures the max length option for the Root part. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| pattern | `RegExp \| string` | - | option | Configures the pattern option for the Root part. | - |
| readOnly | `boolean` | false | option | Marks the control as read-only. | - |
| required | `boolean` | false | option | Marks the form control as required. | - |
| onValueChange | `(value: string, details: InputOtpValueChangeDetails) => void` | - | callback | Runs when the Input OTP value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-input-otp` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-id` | prop | - | Reflects the id prop on the Root part. |
| `data-max-length` | prop | - | Reflects the max length prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-pattern` | prop | - | Reflects the pattern prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
| `data-value` | state | - | Reflects the value state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `string` | value | defaultValue | `data-value` | `getValue` | `setValue` | Tracks the current Input OTP value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `string` | InputOtpValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Input OTP. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Input OTP value from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Input OTP is disabled from Runtime code. |
| `setFormOptions` | props: form, id, name, required | - | No | Updates Input OTP form-related options from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-input-otp`, `data-default-value`, `data-disabled`, `data-form`, `data-id`, `data-max-length`, `data-name`, `data-pattern`, `data-readonly`, `data-required`, `data-value`, `aria-disabled`, `tabindex` | The focusable root needs initial value, disabled, form, pattern, and range metadata before runtime hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, value |
| Hidden input | input (text) |

### Input
The native input synchronized by Input OTP.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-input-otp-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-input-otp-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-input-otp-input`, `autocomplete`, `class`, `form`, `id`, `inputmode`, `maxlength`, `name`, `readonly`, `required`, `tabindex`, `value` | The native one-time-code input must participate in forms and mobile OTP affordances before hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, value |
| Hidden input | input (text) |

### Group
Groups related Input OTP items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-input-otp-group` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-input-otp-group` | runtime | - | Marks the Group part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| group | Yes |

### Slot
A character slot inside Input OTP.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-input-otp-slot` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| index | `number` | - | option | Configures the index option for the Slot part. | - |
| caret | `React.ReactNode` | - | rendering | Changes how the Slot part is rendered. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-input-otp-slot` | runtime | - | Marks the Slot part so Starwind Runtime can find it. |
| `data-index` | prop | - | Reflects the index prop on the Slot part. |
#### Refs
| Part | Public |
| --- | --- |
| slot | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-input-otp-slot`, `data-index` | Slots need stable indices before the runtime writes characters and active state. |

### Slot Char
The visible character rendered in a Input OTP slot.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-input-otp-char` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-input-otp-char` | runtime | - | Marks the Slot Char part so Starwind Runtime can find it. |

### Slot Caret
The caret shown inside the active Input OTP slot.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-input-otp-caret` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-input-otp-caret` | runtime | - | Marks the Slot Caret part so Starwind Runtime can find it. |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-input-otp-caret`, `class`, `hidden` | Carets start hidden until the runtime marks the active empty slot. |

### Separator
Separates groups of Input OTP items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-input-otp-separator` |
| Role | `separator` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-input-otp-separator` | runtime | - | Marks the Separator part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| separator | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-input-otp-separator`, `aria-hidden`, `role` | Separators are presentation-only between slot groups. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createInputOtp`](/docs/runtime/#create-input-otp) |
| Import | `@starwind-ui/runtime/input-otp` |
| Root part | root |
| Option props | defaultValue, disabled, form, id, maxLength, name, onValueChange, pattern, readOnly, required, value |
| Option lifecycles | defaultValue: constructor-only, disabled: setter-backed, form: setter-backed, id: setter-backed, maxLength: refresh-required, name: setter-backed, onValueChange: constructor-only, pattern: constructor-only, readOnly: constructor-only, required: setter-backed, value: setter-backed |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, value |
| Hidden input | input (text) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Input Otp](/docs/components/input-otp/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/input-otp` | `createInputOtp` |
| Astro Primitive | `@starwind-ui/astro/input-otp` | `InputOtp`, `InputOtpRoot`, `InputOtpGroup`, `InputOtpSlot`, `InputOtpSeparator` |
| React Primitive | `@starwind-ui/react/input-otp` | `InputOtp`, `InputOtpRoot`, `InputOtpGroup`, `InputOtpSlot`, `InputOtpSeparator` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `InputOtp` |
| runtime-factory | `createInputOtp` |
| part | `InputOtp.Root` |
| part | `InputOtp.Group` |
| part | `InputOtp.Slot` |
| part | `InputOtp.Separator` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced segmented value state, keyboard and paste handling, form participation, and value-change events.

---

Source: [https://starwind.dev/docs/primitives/menu/](https://starwind.dev/docs/primitives/menu/) · [Markdown](https://starwind.dev/docs/primitives/menu.md)

# Menu Primitive

Menu is a Starwind Runtime primitive in the composite-menu-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Menu anatomy with the Runtime wiring included.
```astro
---
import { Menu } from "@starwind-ui/astro/menu";
---

<Menu.Root>
  <Menu.Trigger>Open menu</Menu.Trigger>
  <Menu.Positioner>
    <Menu.Popup>
      <Menu.Item>Edit</Menu.Item>
    </Menu.Popup>
  </Menu.Positioner>
</Menu.Root>
```

### React
Use the React primitive adapter when Menu state participates in React rendering.
```tsx
import { Menu } from "@starwind-ui/react/menu";

export function Example() {
  return (
    <Menu.Root>
      <Menu.Trigger>Open menu</Menu.Trigger>
      <Menu.Positioner>
        <Menu.Popup>
          <Menu.Item>Edit</Menu.Item>
        </Menu.Popup>
      </Menu.Positioner>
    </Menu.Root>
  );
}
```

### HTML
Render the Menu data-sw-* contract yourself, then initialize createMenu.
```html
<div data-sw-menu>
  <button data-sw-menu-trigger type="button" aria-haspopup="menu">Open menu</button>
  <div data-sw-menu-positioner>
    <div data-sw-menu-popup role="menu" tabindex="-1" hidden>
      <div data-sw-menu-item role="menuitem" tabindex="0">Edit</div>
    </div>
  </div>
</div>

const root = document.querySelector("[data-sw-menu]");
  if (root) {
    createMenu(root);
  }
</script>
```
## Menu Behavior
Menu uses a trigger, popup, and item parts to coordinate open state, keyboard navigation, floating placement, and item activation from one Runtime-owned root.
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | trigger |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, avoidCollisions |
## API Reference
### Root
The main element that owns the Menu Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Menu is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Menu starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| modal | `boolean` | false | option | Makes Menu behave as a modal overlay. | - |
| openOnHover | `boolean` | false | option | Configures the open on hover option for the Root part. | - |
| closeDelay | `number` | 200 | option | Sets how long Menu waits before closing. | - |
| onCloseComplete | `(open: boolean, details: MenuCloseCompleteDetails) => void` | - | callback | Runs after Menu has finished closing. | - |
| onOpenChange | `(open: boolean, details: MenuOpenChangeDetails) => void` | - | callback | Runs when Menu opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-open-on-hover` | prop | - | Reflects the open on hover prop on the Root part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Menu is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | - | - | Tracks whether Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| radioValue | `string` | value | defaultValue | `data-value` | - | - | Tracks the selected radio value for Menu. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | MenuOpenChangeDetails | before-state-commit | Yes | Fires when Menu opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| closeComplete | onCloseComplete | starwind:close-complete | open: `boolean` | MenuCloseCompleteDetails | after-state-commit | No | Fires after Menu has finished closing. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Menu from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| menu-radio-group | provides | value, defaultValue, onValueChange |
| menu-radio-group | consumes | value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu`, `data-default-open`, `data-disabled`, `data-modal`, `data-open-on-hover`, `data-close-delay`, `data-state` | The menu root needs open, disabled, modal, hover, delay, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Menu content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-menu-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | false | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-trigger`, `type`, `aria-haspopup`, `aria-expanded`, `data-state` | Triggers need button semantics, menu affordances, and initial closed state before listeners attach. |

### Portal
Moves Menu overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Positioner
Positions the Menu content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Menu content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Menu content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Menu content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Menu content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Positioner part. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |
#### Refs
| Part | Public |
| --- | --- |
| positioner | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-positioner`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions` | The floating positioner carries initial placement hints used by the shared floating runtime. |

### Popup
The floating content container for Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-popup` |
| Role | `menu` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Menu content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Menu content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Menu content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Menu content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-popup`, `role`, `tabindex`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions`, `hidden` | The popup starts hidden and closed with menu semantics and placement hints before runtime positioning. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Item
An interactive item inside the Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-item` |
| Role | `menuitem` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Item part. | - |
| closeOnClick | `boolean` | true | option | Closes Menu after the item is clicked. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Item part. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-item`, `role`, `tabindex`, `data-close-on-click`, `aria-disabled`, `data-disabled` | Regular menu items need menu item semantics, disabled markers, and optional close behavior markers before activation. |

### Link Item
A link-style item inside the Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `a` |
| Discovery hook | `data-sw-menu-link-item` |
| Role | `menuitem` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Link Item part. | - |
| closeOnClick | `boolean` | false | option | Closes Menu after the item is clicked. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-link-item` | runtime | - | Marks the Link Item part so Starwind Runtime can find it. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Link Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Link Item part. |
#### Refs
| Part | Public |
| --- | --- |
| linkItem | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-link-item`, `role`, `tabindex`, `data-close-on-click`, `aria-disabled`, `data-disabled` | Link menu items need anchor semantics, disabled markers, and optional close behavior markers before activation. |

### Checkbox Item
A checkbox-style item inside the Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-checkbox-item` |
| Role | `menuitemcheckbox` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Checkbox Item part. | - |
| checked | `boolean` | - | control | Controls whether Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| defaultChecked | `boolean` | false | control | Sets whether Menu starts checked for uncontrolled usage. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| closeOnClick | `boolean` | false | option | Closes Menu after the item is clicked. | - |
| onCheckedChange | `(checked: boolean, details: MenuCheckedChangeDetails) => void` | - | callback | Runs when the Menu checked state changes. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-checkbox-item` | runtime | - | Marks the Checkbox Item part so Starwind Runtime can find it. |
| `data-default-checked` | state | - | Reflects the default checked state on the Checkbox Item part. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Checkbox Item part. |
| `data-checked` | state | - | Reflects the checked state on the Checkbox Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Checkbox Item part. |
| `data-unchecked` | state | - | Reflects the unchecked state on the Checkbox Item part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | - | - | Tracks whether Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checkedChange | onCheckedChange | starwind:checked-change | checked: `boolean` | MenuCheckedChangeDetails | before-state-commit | Yes | Fires when the checked state changes for Menu. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Refs
| Part | Public |
| --- | --- |
| checkboxItem | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-checkbox-item`, `data-default-checked`, `data-close-on-click`, `role`, `aria-checked`, `aria-disabled`, `data-checked`, `data-disabled`, `data-unchecked`, `tabindex` | Checkbox menu items need checked, disabled, and close behavior markers before item activation. |

### Checkbox Item Indicator
Shows the checked state for a Menu checkbox item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-menu-checkbox-item-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-checkbox-item-indicator` | runtime | - | Marks the Checkbox Item Indicator part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Checkbox Item Indicator part. |
#### Refs
| Part | Public |
| --- | --- |
| checkboxItemIndicator | Yes |

### Radio Group
Groups related radio items inside Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-radio-group` |
| Role | `group` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `string` | - | control | Controls the current Menu value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
| defaultValue | `string` | - | control | Sets the initial Menu value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
| onValueChange | `(value: string, details: MenuValueChangeDetails) => void` | - | callback | Runs when the Menu value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-radio-group` | runtime | - | Marks the Radio Group part so Starwind Runtime can find it. |
| `data-value` | state | - | Reflects the value state on the Radio Group part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| radioValue | `string` | value | defaultValue | `data-value` | - | - | Tracks the selected radio value for Menu. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `string` | MenuValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Menu. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Refs
| Part | Public |
| --- | --- |
| radioGroup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-radio-group`, `role`, `data-value` | Radio groups need a value marker before runtime normalizes descendant radio item state. |

### Radio Item
A radio-style item inside the Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-radio-item` |
| Role | `menuitemradio` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Radio Item part. | - |
| checked | `boolean` | - | control | Controls whether Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| defaultChecked | `boolean` | false | control | Sets whether Menu starts checked for uncontrolled usage. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| closeOnClick | `boolean` | false | option | Closes Menu after the item is clicked. | - |
| value | `string` | - | option | Controls the current Menu value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-radio-item` | runtime | - | Marks the Radio Item part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Radio Item part. |
| `data-default-checked` | state | - | Reflects the default checked state on the Radio Item part. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Radio Item part. |
| `data-checked` | state | - | Reflects the checked state on the Radio Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Radio Item part. |
| `data-unchecked` | state | - | Reflects the unchecked state on the Radio Item part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | - | - | Tracks whether Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| radioValue | `string` | value | defaultValue | `data-value` | - | - | Tracks the selected radio value for Menu. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Refs
| Part | Public |
| --- | --- |
| radioItem | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-radio-item`, `data-value`, `data-default-checked`, `data-close-on-click`, `role`, `aria-checked`, `aria-disabled`, `data-checked`, `data-disabled`, `data-unchecked`, `tabindex` | Radio menu items need value, checked, disabled, and close behavior markers before item activation. |

### Radio Item Indicator
Shows the selected state for a Menu radio item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-menu-radio-item-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-radio-item-indicator` | runtime | - | Marks the Radio Item Indicator part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Radio Item Indicator part. |
#### Refs
| Part | Public |
| --- | --- |
| radioItemIndicator | Yes |

### Group
Groups related Menu items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-group` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-group` | runtime | - | Marks the Group part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| group | Yes |

### Label
Text label associated with Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |

### Separator
Separates groups of Menu items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-separator` |
| Role | `separator` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-separator` | runtime | - | Marks the Separator part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| separator | Yes |

### Shortcut
Displays keyboard shortcut text for a Menu item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-menu-shortcut` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-shortcut` | runtime | - | Marks the Shortcut part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| shortcut | Yes |

### Submenu Root
Owns a nested submenu inside Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-submenu-root` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| closeDelay | `number` | 200 | option | Sets how long Menu waits before closing. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-submenu-root` | runtime | - | Marks the Submenu Root part so Starwind Runtime can find it. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Submenu Root part. |
| `data-state` | state | - | Reflects the current state on the Submenu Root part. |
#### Refs
| Part | Public |
| --- | --- |
| submenuRoot | Yes |

### Submenu Trigger
Opens a nested submenu inside Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-submenu-trigger` |
| Role | `menuitem` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Submenu Trigger part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-submenu-trigger` | runtime | - | Marks the Submenu Trigger part so Starwind Runtime can find it. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Submenu Trigger part. |
| `data-state` | state | - | Reflects the current state on the Submenu Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| submenuTrigger | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-submenu-trigger`, `role`, `aria-haspopup`, `aria-expanded`, `aria-disabled`, `data-disabled`, `data-state`, `tabindex` | Submenu triggers need menu item semantics and closed disclosure state before nested menu listeners attach. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createMenu`](/docs/runtime/#create-menu) |
| Import | `@starwind-ui/runtime/menu` |
| Root part | root |
| Option props | closeDelay, defaultOpen, disabled, modal, onCloseComplete, onOpenChange, open, openOnHover |
| Option lifecycles | closeDelay: constructor-only, defaultOpen: constructor-only, disabled: constructor-only, modal: constructor-only, onCloseComplete: constructor-only, onOpenChange: constructor-only, open: setter-backed, openOnHover: constructor-only |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Dropdown](/docs/components/dropdown/) | Renamed Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/menu` | `createMenu` |
| Astro Primitive | `@starwind-ui/astro/menu` | `Menu`, `MenuRoot`, `MenuTrigger`, `MenuPortal`, `MenuPositioner`, `MenuPopup`, `MenuItem`, `MenuLinkItem`, `MenuCheckboxItem`, `MenuCheckboxItemIndicator`, `MenuRadioGroup`, `MenuRadioItem`, `MenuRadioItemIndicator`, `MenuGroup`, `MenuLabel`, `MenuSeparator`, `MenuShortcut`, `MenuSubmenuRoot`, `MenuSubmenuTrigger` |
| React Primitive | `@starwind-ui/react/menu` | `Menu`, `MenuRoot`, `MenuTrigger`, `MenuPortal`, `MenuPositioner`, `MenuPopup`, `MenuItem`, `MenuLinkItem`, `MenuCheckboxItem`, `MenuCheckboxItemIndicator`, `MenuRadioGroup`, `MenuRadioItem`, `MenuRadioItemIndicator`, `MenuGroup`, `MenuLabel`, `MenuSeparator`, `MenuShortcut`, `MenuSubmenuRoot`, `MenuSubmenuTrigger` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Menu` |
| runtime-factory | `createMenu` |
| part | `Menu.Root` |
| part | `Menu.Trigger` |
| part | `Menu.Portal` |
| part | `Menu.Positioner` |
| part | `Menu.Popup` |
| part | `Menu.Item` |
| part | `Menu.LinkItem` |
| part | `Menu.CheckboxItem` |
| part | `Menu.CheckboxItemIndicator` |
| part | `Menu.RadioGroup` |
| part | `Menu.RadioItem` |
| part | `Menu.RadioItemIndicator` |
| part | `Menu.Group` |
| part | `Menu.Label` |
| part | `Menu.Separator` |
| part | `Menu.Shortcut` |
| part | `Menu.SubmenuRoot` |
| part | `Menu.SubmenuTrigger` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.1
- Added opt-in modal background-scroll locking while the menu is open.
### v0.1.0
- Introduced action and link items, keyboard navigation, checked items, submenus, and floating placement.

---

Source: [https://starwind.dev/docs/primitives/navigation-menu/](https://starwind.dev/docs/primitives/navigation-menu/) · [Markdown](https://starwind.dev/docs/primitives/navigation-menu.md)

# Navigation Menu Primitive

Navigation Menu coordinates a single active top-level item, shared viewport content, hover timing, keyboard movement, and link close behavior for site navigation.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Usage Guidelines
- **Use Navigation Menu for top-level site or product navigation.** Use it when a row or column of triggers reveals rich panels that share one viewport.
- **Use Menu or Popover for isolated actions.** Navigation Menu is value-driven and viewport-driven, so it is heavier than a single contextual popup.
## Anatomy
### Astro
Use the Astro primitive adapter to render NavigationMenu anatomy with the Runtime wiring included.
```astro
---
import { NavigationMenu } from "@starwind-ui/astro/navigation-menu";
---

<NavigationMenu.Root>
  <NavigationMenu.List>
    <NavigationMenu.Item value="products">
      <NavigationMenu.Trigger>
        <NavigationMenu.Icon>v</NavigationMenu.Icon>
      </NavigationMenu.Trigger>
      <NavigationMenu.Content>
        <NavigationMenu.Link href="/docs">Docs</NavigationMenu.Link>
      </NavigationMenu.Content>
    </NavigationMenu.Item>
  </NavigationMenu.List>
  <NavigationMenu.Portal>
    <NavigationMenu.Positioner>
      <NavigationMenu.Popup>
        <NavigationMenu.Viewport />
        <NavigationMenu.Arrow />
      </NavigationMenu.Popup>
    </NavigationMenu.Positioner>
  </NavigationMenu.Portal>
</NavigationMenu.Root>
```

### React
Use the React primitive adapter when NavigationMenu state participates in React rendering.
```tsx
import { NavigationMenu } from "@starwind-ui/react/navigation-menu";

export function Example() {
  return (
    <NavigationMenu.Root>
      <NavigationMenu.List>
        <NavigationMenu.Item value="products">
          <NavigationMenu.Trigger>
            <NavigationMenu.Icon>v</NavigationMenu.Icon>
          </NavigationMenu.Trigger>
          <NavigationMenu.Content>
            <NavigationMenu.Link href="/docs">Docs</NavigationMenu.Link>
          </NavigationMenu.Content>
        </NavigationMenu.Item>
      </NavigationMenu.List>
      <NavigationMenu.Portal>
        <NavigationMenu.Positioner>
          <NavigationMenu.Popup>
            <NavigationMenu.Viewport />
            <NavigationMenu.Arrow />
          </NavigationMenu.Popup>
        </NavigationMenu.Positioner>
      </NavigationMenu.Portal>
    </NavigationMenu.Root>
  );
}
```

### HTML
Render the NavigationMenu data-sw-* contract yourself, then initialize createNavigationMenu.
```html
<nav data-sw-nav-menu>
  <ul data-sw-nav-menu-list>
    <li data-sw-nav-menu-item data-value="products">
      <button data-sw-nav-menu-trigger type="button" aria-haspopup="menu">
        <span data-sw-nav-menu-icon aria-hidden="true">v</span>
      </button>
      <div data-sw-nav-menu-content hidden>
        <a data-sw-nav-menu-link href="/docs">Docs</a>
      </div>
    </li>
  </ul>
  <div data-sw-nav-menu-portal>
    <div data-sw-nav-menu-positioner>
      <div data-sw-nav-menu-popup hidden>
        <div data-sw-nav-menu-viewport hidden></div>
        <div data-sw-nav-menu-arrow aria-hidden="true"></div>
      </div>
    </div>
  </div>
</nav>

const root = document.querySelector("[data-sw-nav-menu]");
  if (root) {
    createNavigationMenu(root);
  }
</script>
```
## Shared Viewport
Content panels are authored inside items, then moved into the shared viewport while active so the popup can animate size and direction consistently.
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | trigger |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding |
## API Reference
### Root
The navigation landmark that owns the active value, orientation, hover timing, dismissal options, and Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `nav` |
| Discovery hook | `data-sw-nav-menu` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `string \| null` | - | control | Controls the active item value when a framework adapter owns state. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `string \| null` | null | control | Sets the initial uncontrolled active item value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| openDelay | `number` | 50 | option | Sets the default hover-open delay in milliseconds. | - |
| closeDelay | `number` | 50 | option | Sets the default hover-close delay in milliseconds. | - |
| closeOnEscape | `boolean` | true | option | Closes Navigation Menu when Escape is pressed. | - |
| closeOnOutsideInteract | `boolean` | true | option | Closes Navigation Menu when the user interacts outside it. | - |
| onValueChange | `(value: string \| null, details: NavigationMenuValueChangeDetails) => void` | - | callback | Runs when the Navigation Menu value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| orientation | `"horizontal" \| "vertical"` | "horizontal" | option | Sets horizontal or vertical trigger keyboard movement. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu` | runtime | - | Runtime discovery hook for the Navigation Menu root. |
| `data-value` | prop | - | Reflects the value prop on the Root part. |
| `data-controlled-value` | prop | - | Reflects the controlled value prop on the Root part. |
| `data-default-value` | prop | - | Initial uncontrolled active item value. |
| `data-open-delay` | prop | - | Reflects the open delay prop on the Root part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Root part. |
| `data-close-on-escape` | prop | - | Reflects the close on escape prop on the Root part. |
| `data-close-on-outside-interact` | prop | - | Reflects the close on outside interact prop on the Root part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Root part. |
| `data-state` | state | - | Reflects whether any item is open. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `string \| null` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Navigation Menu value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `string \| null` | NavigationMenuValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Navigation Menu. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Navigation Menu value from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-nav-menu`, `data-default-value`, `data-open-delay`, `data-close-delay`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-orientation`, `data-state` | The root needs initial value, dismissal, orientation, and closed state before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### List
The list of selectable Navigation Menu items.
| Fact | Value |
| --- | --- |
| Default element | `ul` |
| Discovery hook | `data-sw-nav-menu-list` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-list` | runtime | - | Marks the List part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| list | Yes |

### Item
An interactive item inside the Navigation Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `li` |
| Discovery hook | `data-sw-nav-menu-item` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `string` | - | option | Controls the current Navigation Menu value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Item part. |
| `data-state` | state | - | Reflects the current state on the Item part. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |

### Trigger
The button or asChild control that opens, closes, and keyboard-targets a content panel.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-nav-menu-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| openDelay | `number` | 50 | option | Overrides root hover-open timing for this trigger. | - |
| closeDelay | `number` | 50 | option | Overrides root hover-close timing for this trigger. | - |
| asChild | `boolean` | - | rendering | Merges trigger behavior into the slotted child control. | - |
| disabled | `boolean` | false | option | Prevents trigger interaction and removes it from roving trigger movement. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-trigger` | runtime | - | Runtime discovery hook for the trigger part. |
| `data-as-child` | prop | - | Reflects the as child prop on the Trigger part. |
| `data-open-delay` | prop | - | Reflects the open delay prop on the Trigger part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Trigger part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Trigger part. |
| `data-state` | state | - | Reflects whether this trigger's item is open. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref, style |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-nav-menu-trigger`, `type`, `data-as-child`, `data-open-delay`, `data-close-delay`, `aria-haspopup`, `aria-expanded`, `data-disabled`, `data-state` | Triggers need button semantics and closed ARIA state before hydration. |

### Icon
Decorative icon rendered by Navigation Menu.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-nav-menu-icon` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-icon` | runtime | - | Marks the Icon part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Icon part. |
#### Refs
| Part | Public |
| --- | --- |
| icon | Yes |

### Content
The authored item panel. The Runtime moves the active content into the shared viewport.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-nav-menu-content` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-content` | runtime | - | Runtime discovery hook for the content part. |
| `data-state` | state | - | Reflects whether this content panel is active. |
#### Refs
| Part | Public |
| --- | --- |
| content | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-nav-menu-content`, `data-state`, `hidden` | Content starts hidden until the runtime moves the active panel into the viewport. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Link
A navigation link inside content. Links close the active menu by default and can mark current-page state.
| Fact | Value |
| --- | --- |
| Default element | `a` |
| Discovery hook | `data-sw-nav-menu-link` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| href | `string` | - | attribute | Sets the href attribute on the Link part. | - |
| active | `boolean` | false | option | Marks the link as active and sets aria-current. | - |
| closeOnClick | `boolean` | true | option | Controls whether clicking the link closes the menu. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-link` | runtime | - | Runtime discovery hook for the link part. |
| `data-active` | prop | - | Present when the link is active. |
| `data-close-on-click` | prop | - | Set to false to keep the menu open after link activation. |
#### Refs
| Part | Public |
| --- | --- |
| link | Yes |

### Portal
Moves Navigation Menu overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-nav-menu-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Positioner
The floating positioning part for the shared popup.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-nav-menu-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for the popup. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets popup alignment relative to the active trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between the popup and trigger. | - |
| alignOffset | `number` | 0 | option | Adjusts the cross-axis alignment offset for Navigation Menu content. | - |
| avoidCollisions | `boolean` | true | option | Allows the popup to shift or flip to remain visible. | - |
| collisionPadding | `number` | 8 | option | Configures the collision padding option for the Positioner part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-positioner` | runtime | - | Runtime discovery hook for the positioner part. |
| `data-state` | state | - | Reflects the current state on the Positioner part. |
| `data-side` | prop | - | Reflects the resolved floating side. |
| `data-align` | prop | - | Reflects the resolved floating alignment. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-align-offset` | prop | - | Reflects the align offset prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |
| `data-collision-padding` | prop | - | Reflects the collision padding prop on the Positioner part. |
#### Refs
| Part | Public |
| --- | --- |
| positioner | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-nav-menu-positioner`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-align-offset`, `data-avoid-collisions`, `data-collision-padding` | The positioner owns initial floating options before hydration. |

### Popup
The floating content container for Navigation Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-nav-menu-popup` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Navigation Menu content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Navigation Menu content aligns to its trigger. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-nav-menu-popup`, `data-state`, `hidden` | The popup starts hidden until a trigger activates a panel. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Viewport
The shared visible container that receives active item content and carries measured size state.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-nav-menu-viewport` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-viewport` | runtime | - | Runtime discovery hook for the viewport part. |
| `data-state` | state | - | Reflects whether any content is visible. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-nav-menu-viewport`, `data-state`, `hidden` | The shared viewport starts hidden and receives active content at runtime. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Arrow
The arrow element that visually points to the trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-nav-menu-arrow` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-nav-menu-arrow` | runtime | - | Marks the Arrow part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Arrow part. |
#### Refs
| Part | Public |
| --- | --- |
| arrow | Yes |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createNavigationMenu`](/docs/runtime/#create-navigation-menu) |
| Import | `@starwind-ui/runtime/navigation-menu` |
| Root part | root |
| Option props | closeDelay, closeOnEscape, closeOnOutsideInteract, defaultValue, onValueChange, openDelay, value |
| Option lifecycles | closeDelay: constructor-only, closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultValue: constructor-only, onValueChange: constructor-only, openDelay: constructor-only, value: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Navigation Menu](/docs/components/navigation-menu/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/navigation-menu` | `createNavigationMenu` |
| Astro Primitive | `@starwind-ui/astro/navigation-menu` | `NavigationMenu`, `NavigationMenuRoot`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuIcon`, `NavigationMenuContent`, `NavigationMenuLink`, `NavigationMenuPortal`, `NavigationMenuPositioner`, `NavigationMenuPopup`, `NavigationMenuViewport`, `NavigationMenuArrow` |
| React Primitive | `@starwind-ui/react/navigation-menu` | `NavigationMenu`, `NavigationMenuRoot`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuIcon`, `NavigationMenuContent`, `NavigationMenuLink`, `NavigationMenuPortal`, `NavigationMenuPositioner`, `NavigationMenuPopup`, `NavigationMenuViewport`, `NavigationMenuArrow` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `NavigationMenu` |
| runtime-factory | `createNavigationMenu` |
| part | `NavigationMenu.Root` |
| part | `NavigationMenu.List` |
| part | `NavigationMenu.Item` |
| part | `NavigationMenu.Trigger` |
| part | `NavigationMenu.Icon` |
| part | `NavigationMenu.Content` |
| part | `NavigationMenu.Link` |
| part | `NavigationMenu.Portal` |
| part | `NavigationMenu.Positioner` |
| part | `NavigationMenu.Popup` |
| part | `NavigationMenu.Viewport` |
| part | `NavigationMenu.Arrow` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced navigation-menu state, keyboard interaction, indicator positioning, and shared viewport behavior.

---

Source: [https://starwind.dev/docs/primitives/popover/](https://starwind.dev/docs/primitives/popover/) · [Markdown](https://starwind.dev/docs/primitives/popover.md)

# Popover Primitive

Popover is a Starwind Runtime primitive in the presence-floating-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Popover anatomy with the Runtime wiring included.
```astro
---
import { Popover } from "@starwind-ui/astro/popover";
---

<Popover.Root>
  <Popover.Trigger>Open popover</Popover.Trigger>
  <Popover.Backdrop />
  <Popover.Positioner>
    <Popover.Popup>
      <Popover.Title>Popover title</Popover.Title>
      <Popover.Description>Popover description</Popover.Description>
      <Popover.Close>Close</Popover.Close>
      <Popover.Arrow />
    </Popover.Popup>
  </Popover.Positioner>
</Popover.Root>
```

### React
Use the React primitive adapter when Popover state participates in React rendering.
```tsx
import { Popover } from "@starwind-ui/react/popover";

export function Example() {
  return (
    <Popover.Root>
      <Popover.Trigger>Open popover</Popover.Trigger>
      <Popover.Backdrop />
      <Popover.Positioner>
        <Popover.Popup>
          <Popover.Title>Popover title</Popover.Title>
          <Popover.Description>Popover description</Popover.Description>
          <Popover.Close>Close</Popover.Close>
          <Popover.Arrow />
        </Popover.Popup>
      </Popover.Positioner>
    </Popover.Root>
  );
}
```

### HTML
Render the Popover data-sw-* contract yourself, then initialize createPopover.
```html
<div data-sw-popover>
  <button data-sw-popover-trigger type="button" aria-haspopup="dialog">Open popover</button>
  <div data-sw-popover-backdrop hidden></div>
  <div data-sw-popover-positioner>
    <div data-sw-popover-popup role="dialog" tabindex="-1" hidden>
      <h2 data-sw-popover-title>Popover title</h2>
      <p data-sw-popover-description>Popover description</p>
      <button data-sw-popover-close type="button">Close</button>
      <div data-sw-popover-arrow></div>
    </div>
  </div>
</div>

const root = document.querySelector("[data-sw-popover]");
  if (root) {
    createPopover(root);
  }
</script>
```
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | trigger |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, avoidCollisions, collisionStrategy |
## API Reference
### Root
The main element that owns the Popover Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Popover is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Popover starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| closeOnEscape | `boolean` | true | option | Closes Popover when Escape is pressed. | - |
| closeOnOutsideInteract | `boolean` | true | option | Closes Popover when the user interacts outside it. | - |
| modal | `boolean` | false | option | Makes Popover behave as a modal overlay. | - |
| openOnHover | `boolean` | false | option | Configures the open on hover option for the Root part. | - |
| closeDelay | `number` | 200 | option | Sets how long Popover waits before closing. | - |
| onCloseComplete | `(open: boolean, details: PopoverCloseCompleteDetails) => void` | - | callback | Runs after Popover has finished closing. | - |
| onOpenChange | `(open: boolean, details: PopoverOpenChangeDetails) => void` | - | callback | Runs when Popover opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-close-on-escape` | prop | - | Reflects the close on escape prop on the Root part. |
| `data-close-on-outside-interact` | prop | - | Reflects the close on outside interact prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-open-on-hover` | prop | - | Reflects the open on hover prop on the Root part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Popover is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | PopoverOpenChangeDetails | before-state-commit | Yes | Fires when Popover opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| closeComplete | onCloseComplete | starwind:close-complete | open: `boolean` | PopoverCloseCompleteDetails | after-state-commit | No | Fires after Popover has finished closing. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Popover from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-popover`, `data-default-open`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-open-on-hover`, `data-close-delay`, `data-state` | The popover root needs default-open, dismissal, hover, close-delay, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Popover content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-popover-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-as-child` | prop | - | Reflects the as child prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-popover-trigger`, `data-as-child`, `aria-haspopup`, `aria-expanded`, `data-state`, `type` | Triggers need dialog affordances, asChild markers, and initial closed state before activation listeners attach. |

### Portal
Moves Popover overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Positioner
Positions the Popover content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Popover content. | - |
| align | `"start" \| "center" \| "end"` | "center" | option | Sets how Popover content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Popover content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Popover content to shift or flip to stay visible. | - |
| collisionStrategy | `"initial-placement" \| "best-fit"` | "initial-placement" | option | Configures the collision strategy option for the Positioner part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Positioner part. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |
| `data-collision-strategy` | prop | - | Reflects the collision strategy prop on the Positioner part. |
#### Refs
| Part | Public |
| --- | --- |
| positioner | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-popover-positioner`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions`, `data-collision-strategy` | The positioner carries initial placement hints used by the shared floating runtime. |

### Popup
The floating content container for Popover.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-popup` |
| Role | `dialog` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Popover content. | - |
| align | `"start" \| "center" \| "end"` | "center" | option | Sets how Popover content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Popover content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Popover content to shift or flip to stay visible. | - |
| collisionStrategy | `"initial-placement" \| "best-fit"` | "initial-placement" | option | Configures the collision strategy option for the Popup part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
| `data-collision-strategy` | prop | - | Reflects the collision strategy prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-popover-popup`, `role`, `tabindex`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions`, `data-collision-strategy`, `hidden` | The popup starts hidden with dialog semantics, focus targetability, and initial placement hints before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Arrow
The arrow element that visually points to the trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-arrow` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-arrow` | runtime | - | Marks the Arrow part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| arrow | Yes |

### Backdrop
The backdrop shown behind the Popover overlay.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-backdrop` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-backdrop` | runtime | - | Marks the Backdrop part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Backdrop part. |
#### Refs
| Part | Public |
| --- | --- |
| backdrop | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-popover-backdrop`, `data-state`, `hidden` | The optional backdrop starts hidden and receives runtime-owned open/close visibility. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Title
The accessible title for Popover.
| Fact | Value |
| --- | --- |
| Default element | `h2` |
| Discovery hook | `data-sw-popover-title` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-title` | runtime | - | Marks the Title part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| title | Yes |

### Description
Supporting description text for Popover.
| Fact | Value |
| --- | --- |
| Default element | `p` |
| Discovery hook | `data-sw-popover-description` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-description` | runtime | - | Marks the Description part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| description | Yes |

### Close
A control that closes Popover.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-popover-close` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-close` | runtime | - | Marks the Close part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| close | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-popover-close`, `type` | Close controls need button semantics before runtime listeners attach. |

### Viewport
The visible viewport for Popover content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-viewport` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createPopover`](/docs/runtime/#create-popover) |
| Import | `@starwind-ui/runtime/popover` |
| Root part | root |
| Option props | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open, openOnHover |
| Option lifecycles | closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultOpen: constructor-only, modal: constructor-only, onCloseComplete: constructor-only, onOpenChange: constructor-only, open: setter-backed, openOnHover: constructor-only |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Popover](/docs/components/popover/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/popover` | `createPopover` |
| Astro Primitive | `@starwind-ui/astro/popover` | `Popover`, `PopoverRoot`, `PopoverTrigger`, `PopoverPortal`, `PopoverPositioner`, `PopoverPopup`, `PopoverArrow`, `PopoverBackdrop`, `PopoverTitle`, `PopoverDescription`, `PopoverClose`, `PopoverViewport` |
| React Primitive | `@starwind-ui/react/popover` | `Popover`, `PopoverRoot`, `PopoverTrigger`, `PopoverPortal`, `PopoverPositioner`, `PopoverPopup`, `PopoverArrow`, `PopoverBackdrop`, `PopoverTitle`, `PopoverDescription`, `PopoverClose`, `PopoverViewport` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Popover` |
| runtime-factory | `createPopover` |
| part | `Popover.Root` |
| part | `Popover.Trigger` |
| part | `Popover.Portal` |
| part | `Popover.Positioner` |
| part | `Popover.Popup` |
| part | `Popover.Arrow` |
| part | `Popover.Backdrop` |
| part | `Popover.Title` |
| part | `Popover.Description` |
| part | `Popover.Close` |
| part | `Popover.Viewport` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.3
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.2
- Added collision strategy support to the generated Astro and React Primitive adapters for best-fit placement in constrained viewports.
### v0.1.1
- Added modal background-scroll locking when modal behavior is enabled.
### v0.1.0
- Introduced open state, floating placement, focus handling, dismissal, presence, and nesting.

---

Source: [https://starwind.dev/docs/primitives/preview-card/](https://starwind.dev/docs/primitives/preview-card/) · [Markdown](https://starwind.dev/docs/primitives/preview-card.md)

# Preview Card Primitive

Preview Card is a Starwind Runtime primitive in the presence-floating-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render PreviewCard anatomy with the Runtime wiring included.
```astro
---
import { PreviewCard } from "@starwind-ui/astro/preview-card";
---

<PreviewCard.Root>
  <PreviewCard.Trigger>Preview profile</PreviewCard.Trigger>
  <PreviewCard.Positioner>
    <PreviewCard.Popup>
      <PreviewCard.Arrow />
    </PreviewCard.Popup>
  </PreviewCard.Positioner>
</PreviewCard.Root>
```

### React
Use the React primitive adapter when PreviewCard state participates in React rendering.
```tsx
import { PreviewCard } from "@starwind-ui/react/preview-card";

export function Example() {
  return (
    <PreviewCard.Root>
      <PreviewCard.Trigger>Preview profile</PreviewCard.Trigger>
      <PreviewCard.Positioner>
        <PreviewCard.Popup>
          <PreviewCard.Arrow />
        </PreviewCard.Popup>
      </PreviewCard.Positioner>
    </PreviewCard.Root>
  );
}
```

### HTML
Render the PreviewCard data-sw-* contract yourself, then initialize createPreviewCard.
```html
<div data-sw-preview-card>
  <button data-sw-preview-card-trigger type="button">Preview profile</button>
  <div data-sw-preview-card-positioner>
    <div data-sw-preview-card-popup role="tooltip" hidden>
      <div data-sw-preview-card-arrow></div>
    </div>
  </div>
</div>

const root = document.querySelector("[data-sw-preview-card]");
  if (root) {
    createPreviewCard(root);
  }
</script>
```
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | trigger |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, avoidCollisions |
## API Reference
### Root
The main element that owns the Preview Card Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Preview Card is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Preview Card starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| closeDelay | `number` | 300 | option | Sets how long Preview Card waits before closing. | - |
| closeOnEscape | `boolean` | true | option | Closes Preview Card when Escape is pressed. | - |
| closeOnOutsideInteract | `boolean` | true | option | Closes Preview Card when the user interacts outside it. | - |
| disableHoverableContent | `boolean` | false | option | Configures the disable hoverable content option for the Root part. | - |
| openDelay | `number` | 600 | option | Sets how long Preview Card waits before opening. | - |
| onOpenChange | `(open: boolean, details: PreviewCardOpenChangeDetails) => void` | - | callback | Runs when Preview Card opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Root part. |
| `data-close-on-escape` | prop | - | Reflects the close on escape prop on the Root part. |
| `data-close-on-outside-interact` | prop | - | Reflects the close on outside interact prop on the Root part. |
| `data-content-hoverable` | prop | - | Reflects the content hoverable prop on the Root part. |
| `data-open-delay` | prop | - | Reflects the open delay prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Preview Card is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | PreviewCardOpenChangeDetails | before-state-commit | Yes | Fires when Preview Card opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Preview Card from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card`, `data-default-open`, `data-close-delay`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-content-hoverable`, `data-open-delay`, `data-state` | The preview card root needs timing, dismissal, hoverability, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Preview Card content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-preview-card-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. | - |
| disabled | `boolean` | false | option | Disables the Trigger part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-as-child` | prop | - | Reflects the as child prop on the Trigger part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Trigger part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Trigger part. |
| `data-open-delay` | prop | - | Reflects the open delay prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-trigger`, `data-as-child`, `data-close-delay`, `data-disabled`, `data-open-delay`, `aria-disabled`, `data-state`, `disabled`, `type` | Triggers need delay overrides, disabled state, and initial closed state before pointer/focus listeners attach. |

### Portal
Moves Preview Card overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Positioner
Positions the Preview Card content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Preview Card content. | - |
| align | `"start" \| "center" \| "end"` | "center" | option | Sets how Preview Card content aligns to its trigger. | - |
| sideOffset | `number` | 0 | option | Sets the distance between Preview Card content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Preview Card content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Positioner part. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |
#### Refs
| Part | Public |
| --- | --- |
| positioner | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-positioner`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions` | The positioner carries initial placement hints used by the shared floating runtime. |

### Popup
The floating content container for Preview Card.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-popup` |
| Role | `tooltip` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Preview Card content. | - |
| align | `"start" \| "center" \| "end"` | "center" | option | Sets how Preview Card content aligns to its trigger. | - |
| sideOffset | `number` | 0 | option | Sets the distance between Preview Card content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Preview Card content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-popup`, `role`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions`, `hidden` | The preview card popup starts hidden with tooltip semantics and initial placement hints before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Arrow
The arrow element that visually points to the trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-arrow` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-arrow` | runtime | - | Marks the Arrow part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Arrow part. |
#### Refs
| Part | Public |
| --- | --- |
| arrow | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-arrow`, `data-state` | The optional arrow receives state and placement updates from the floating runtime. |

### Backdrop
The backdrop shown behind the Preview Card overlay.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-backdrop` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-backdrop` | runtime | - | Marks the Backdrop part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Backdrop part. |
#### Refs
| Part | Public |
| --- | --- |
| backdrop | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-backdrop`, `data-state`, `hidden` | The optional backdrop starts hidden and receives runtime-owned visibility state. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Viewport
The visible viewport for Preview Card content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-viewport` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Viewport part. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-viewport`, `data-state` | The optional viewport receives state and placement updates from the floating runtime. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createPreviewCard`](/docs/runtime/#create-preview-card) |
| Import | `@starwind-ui/runtime/preview-card` |
| Root part | root |
| Option props | closeDelay, closeOnEscape, closeOnOutsideInteract, defaultOpen, disableHoverableContent, onOpenChange, open, openDelay |
| Option lifecycles | closeDelay: constructor-only, closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultOpen: constructor-only, disableHoverableContent: constructor-only, onOpenChange: constructor-only, open: setter-backed, openDelay: constructor-only |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Hover Card](/docs/components/hover-card/) | Renamed Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/preview-card` | `createPreviewCard` |
| Astro Primitive | `@starwind-ui/astro/preview-card` | `PreviewCard`, `PreviewCardRoot`, `PreviewCardTrigger`, `PreviewCardPortal`, `PreviewCardPositioner`, `PreviewCardPopup`, `PreviewCardArrow`, `PreviewCardBackdrop`, `PreviewCardViewport` |
| React Primitive | `@starwind-ui/react/preview-card` | `PreviewCard`, `PreviewCardRoot`, `PreviewCardTrigger`, `PreviewCardPortal`, `PreviewCardPositioner`, `PreviewCardPopup`, `PreviewCardArrow`, `PreviewCardBackdrop`, `PreviewCardViewport` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `PreviewCard` |
| runtime-factory | `createPreviewCard` |
| part | `PreviewCard.Root` |
| part | `PreviewCard.Trigger` |
| part | `PreviewCard.Portal` |
| part | `PreviewCard.Positioner` |
| part | `PreviewCard.Popup` |
| part | `PreviewCard.Arrow` |
| part | `PreviewCard.Backdrop` |
| part | `PreviewCard.Viewport` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced hover and focus timing, floating placement, presence, and dismissal for preview content.

---

Source: [https://starwind.dev/docs/primitives/progress/](https://starwind.dev/docs/primitives/progress/) · [Markdown](https://starwind.dev/docs/primitives/progress.md)

# Progress Primitive

Progress is a Starwind Runtime primitive in the static-semantic contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Progress anatomy with the Runtime wiring included.
```astro
---
import { Progress } from "@starwind-ui/astro/progress";
---

<Progress.Root>
  <Progress.Label>Upload progress</Progress.Label>
  <Progress.Track>
    <Progress.Indicator />
  </Progress.Track>
  <Progress.Value>Selected value</Progress.Value>
</Progress.Root>
```

### React
Use the React primitive adapter when Progress state participates in React rendering.
```tsx
import { Progress } from "@starwind-ui/react/progress";

export function Example() {
  return (
    <Progress.Root>
      <Progress.Label>Upload progress</Progress.Label>
      <Progress.Track>
        <Progress.Indicator />
      </Progress.Track>
      <Progress.Value>Selected value</Progress.Value>
    </Progress.Root>
  );
}
```

### HTML
Render the Progress data-sw-* contract yourself, then initialize createProgress.
```html
<div data-sw-progress role="progressbar">
  <span data-sw-progress-label role="presentation">Upload progress</span>
  <div data-sw-progress-track>
    <div data-sw-progress-indicator></div>
  </div>
  <span data-sw-progress-value aria-hidden="true">Selected value</span>
</div>

const root = document.querySelector("[data-sw-progress]");
  if (root) {
    createProgress(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Progress Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-progress` |
| Role | `progressbar` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `number \| null` | null | control | Controls the current Progress value. | **React:** Use value for controlled state.<br>**Astro:** Use value for initial state and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state and call setValue for later updates. |
| max | `number` | 100 | option | Configures the max option for the Root part. | - |
| min | `number` | 0 | option | Configures the min option for the Root part. | - |
| format | `Intl.NumberFormatOptions` | - | option | Configures the format option for the Root part. | - |
| getAriaValueText | `(formattedValue: string \| null, value: ProgressValue) => string` | - | option | Configures the get aria value text option for the Root part. | - |
| locale | `Intl.LocalesArgument` | - | option | Sets the locale used by Progress. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-progress` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-value` | state | - | Reflects the value state on the Root part. |
| `data-min` | prop | - | Reflects the min prop on the Root part. |
| `data-max` | prop | - | Reflects the max prop on the Root part. |
| `data-indeterminate` | state | - | Reflects the indeterminate state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `ProgressValue` | value | - | `data-value` | `getValue` | `setValue` | Tracks the current Progress value. | **React:** Use value for controlled state.<br>**Astro:** Use value for initial state and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state and call setValue for later updates. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setFormatOptions` | props: format, getAriaValueText, locale | - | No | Updates Progress formatting options from Runtime code. |
| `setValue` | props: value, max, min | - | Yes | Updates the current Progress value from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-progress`, `data-value`, `data-min`, `data-max`, `data-indeterminate`, `role` | The progressbar needs deterministic value/range markers and progressbar semantics before the runtime computes ARIA value text. |

### Track
The track that contains the Progress range.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-progress-track` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-progress-track` | runtime | - | Marks the Track part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| track | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-progress-track` | The track is a stable runtime target for status attributes. |

### Indicator
Visual state indicator rendered by Progress.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-progress-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-progress-indicator` | runtime | - | Marks the Indicator part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| indicator | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-progress-indicator` | The indicator is positioned by the runtime after percent calculation. |

### Value
Displays the current Progress value.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-progress-value` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-progress-value` | runtime | - | Marks the Value part so Starwind Runtime can find it. |
| `data-preserve-text` | prop | - | Reflects the preserve text prop on the Value part. |
#### Refs
| Part | Public |
| --- | --- |
| value | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-progress-value`, `aria-hidden`, `data-preserve-text` | Value text is runtime-generated unless the adapter marks caller-provided text for preservation. |

### Label
Text label associated with Progress.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-progress-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-progress-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-progress-label`, `role` | Labels can be linked to the root by the runtime when no explicit ARIA label exists. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createProgress`](/docs/runtime/#create-progress) |
| Import | `@starwind-ui/runtime/progress` |
| Root part | root |
| Option props | format, getAriaValueText, locale, max, min, value |
| Option lifecycles | format: setter-backed, getAriaValueText: setter-backed, locale: setter-backed, max: setter-backed, min: setter-backed, value: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Progress](/docs/components/progress/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/progress` | `createProgress` |
| Astro Primitive | `@starwind-ui/astro/progress` | `Progress`, `ProgressRoot`, `ProgressTrack`, `ProgressIndicator`, `ProgressValue`, `ProgressLabel` |
| React Primitive | `@starwind-ui/react/progress` | `Progress`, `ProgressRoot`, `ProgressTrack`, `ProgressIndicator`, `ProgressValue`, `ProgressLabel` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Progress` |
| runtime-factory | `createProgress` |
| part | `Progress.Root` |
| part | `Progress.Track` |
| part | `Progress.Indicator` |
| part | `Progress.Value` |
| part | `Progress.Label` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced determinate and indeterminate progress state with accessible value metadata.

---

Source: [https://starwind.dev/docs/primitives/radio/](https://starwind.dev/docs/primitives/radio/) · [Markdown](https://starwind.dev/docs/primitives/radio.md)

# Radio Primitive

Radio is a Starwind Runtime primitive in the single-boolean-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Radio anatomy with the Runtime wiring included.
```astro
---
import { Radio } from "@starwind-ui/astro/radio";
---

<Radio.Root value="option-one">
  <Radio.Indicator />
</Radio.Root>
```

### React
Use the React primitive adapter when Radio state participates in React rendering.
```tsx
import { Radio } from "@starwind-ui/react/radio";

export function Example() {
  return (
    <Radio.Root value="option-one">
      <Radio.Indicator />
    </Radio.Root>
  );
}
```

### HTML
Render the Radio data-sw-* contract yourself, then initialize createRadio.
```html
<span data-sw-radio role="radio" data-value="option-one">
  <span data-sw-radio-indicator></span>
  <input data-sw-radio-input type="radio" aria-hidden="true" tabindex="-1" />
</span>

const root = document.querySelector("[data-sw-radio]");
  if (root) {
    createRadio(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Radio Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-radio` |
| Role | `radio` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| checked | `boolean` | - | control | Controls whether Radio is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| defaultChecked | `boolean` | false | control | Sets whether Radio starts checked for uncontrolled usage. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| id | `string` | - | option | Sets the id used by the associated native control. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| nativeButton | `boolean` | false | rendering | Renders the control as a native button element. | - |
| readOnly | `boolean` | false | option | Marks the control as read-only. | - |
| required | `boolean` | false | option | Marks the form control as required. | - |
| value | `string` | - | option | Controls the current Radio value. | - |
| onCheckedChange | `(checked: boolean, details: RadioCheckedChangeDetails) => void` | - | callback | Runs when the Radio checked state changes. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-radio` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-checked` | state | - | Reflects the checked state on the Root part. |
| `data-default-checked` | prop | - | Reflects the default checked prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-id` | prop | - | Reflects the id prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
| `data-unchecked` | state | - | Reflects the unchecked state on the Root part. |
| `data-value` | prop | - | Reflects the value prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | `getChecked` | `setChecked` | Tracks whether Radio is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checkedChange | onCheckedChange | starwind:checked-change | checked: `boolean` | RadioCheckedChangeDetails | before-state-commit | Yes | Fires when the checked state changes for Radio. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setChecked` | state: checked | emit: false | Yes | Updates whether Radio is checked from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Radio is disabled from Runtime code. |
| `setReadOnly` | prop: readOnly | - | No | Updates whether Radio is read-only from Runtime code. |
| `setFormOptions` | props: form, name, required, value | - | No | Updates Radio form-related options from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| radio-group | consumes | disabled, form, name, readOnly, required, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-radio`, `role`, `aria-checked`, `data-checked`, `data-unchecked`, `data-default-checked`, `data-disabled` | The visible radio needs ARIA and state styling before the controller attaches. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, value |
| Hidden input | input (radio) |

### Indicator
Visual state indicator rendered by Radio.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-radio-indicator` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| keepMounted | `boolean` | false | rendering | Keeps the Indicator part in the DOM when hidden. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-radio-indicator` | runtime | - | Marks the Indicator part so Starwind Runtime can find it. |
| `data-keep-mounted` | prop | - | Reflects the keep mounted prop on the Indicator part. |
| `data-unchecked` | state | - | Reflects the unchecked state on the Indicator part. |
#### Refs
| Part | Public |
| --- | --- |
| indicator | Yes |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | keepMounted |

### Input
The native input synchronized by Radio.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-radio-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-radio-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-radio-input` | The runtime needs the hidden input placeholder so it can attach form state after hydration; native button roots place it as a sibling after the visible button. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, value |
| Hidden input | input (radio) |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createRadio`](/docs/runtime/#create-radio) |
| Import | `@starwind-ui/runtime/radio` |
| Root part | root |
| Option props | checked, defaultChecked, disabled, form, id, name, readOnly, required, value |
| Option lifecycles | - |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, value |
| Hidden input | input (radio) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Radio Group](/docs/components/radio-group/) | Composite |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/radio` | `createRadio` |
| Astro Primitive | `@starwind-ui/astro/radio` | `Radio`, `RadioRoot`, `RadioIndicator` |
| React Primitive | `@starwind-ui/react/radio` | `Radio`, `RadioRoot`, `RadioIndicator` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Radio` |
| runtime-factory | `createRadio` |
| part | `Radio.Root` |
| part | `Radio.Indicator` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.1
- Synchronized vendored React Radio state after accepted Runtime transitions and external state changes.
### v0.1.0
- Introduced radio item checked state, disabled behavior, and native form participation.

---

Source: [https://starwind.dev/docs/primitives/radio-group/](https://starwind.dev/docs/primitives/radio-group/) · [Markdown](https://starwind.dev/docs/primitives/radio-group.md)

# Radio Group Primitive

Radio Group is a Starwind Runtime primitive in the controlled-value-group contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render RadioGroup anatomy with the Runtime wiring included.
```astro
---
import { RadioGroup } from "@starwind-ui/astro/radio-group";
---

<RadioGroup.Root />
```

### React
Use the React primitive adapter when RadioGroup state participates in React rendering.
```tsx
import { RadioGroup } from "@starwind-ui/react/radio-group";

export function Example() {
  return (
    <RadioGroup.Root />
  );
}
```

### HTML
Render the RadioGroup data-sw-* contract yourself, then initialize createRadioGroup.
```html
<div data-sw-radio-group role="radiogroup"></div>

const root = document.querySelector("[data-sw-radio-group]");
  if (root) {
    createRadioGroup(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Radio Group Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-radio-group` |
| Role | `radiogroup` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `RadioGroupValue` | - | control | Controls the current Radio Group value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `RadioGroupValue` | - | control | Sets the initial Radio Group value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| orientation | `"horizontal" \| "vertical"` | "vertical" | option | Sets the Radio Group orientation. | - |
| readOnly | `boolean` | false | option | Marks the control as read-only. | - |
| required | `boolean` | false | option | Marks the form control as required. | - |
| onValueChange | `(value: string, details: RadioGroupValueChangeDetails) => void` | - | callback | Runs when the Radio Group value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-radio-group` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
| `data-value` | state | - | Reflects the value state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `RadioGroupValue` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Radio Group value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `string` | RadioGroupValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Radio Group. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Radio Group value from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Radio Group is disabled from Runtime code. |
| `setFormOptions` | props: form, name, required | - | No | Updates Radio Group form-related options from Runtime code. |
| `setName` | prop: name | - | No | Updates the Radio Group form field name from Runtime code. |
| `setOrientation` | prop: orientation | - | No | Updates the Radio Group orientation from Runtime code. |
| `setReadOnly` | prop: readOnly | - | No | Updates whether Radio Group is read-only from Runtime code. |
| `setRequired` | prop: required | - | No | Updates whether Radio Group is required from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| radio-group | provides | disabled, form, name, readOnly, required, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-radio-group`, `role`, `aria-disabled`, `aria-orientation`, `aria-readonly`, `aria-required`, `data-default-value`, `data-disabled`, `data-form`, `data-name`, `data-orientation`, `data-readonly`, `data-required`, `data-value` | The radio group needs initial selection, form coordination, and orientation for child radio semantics before hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, name, required, value |
| Hidden input | - |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createRadioGroup`](/docs/runtime/#create-radio-group) |
| Import | `@starwind-ui/runtime/radio-group` |
| Root part | root |
| Option props | defaultValue, disabled, form, name, orientation, readOnly, required, value |
| Option lifecycles | - |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, name, required, value |
| Hidden input | - |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Radio Group](/docs/components/radio-group/) | Composite |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/radio-group` | `createRadioGroup` |
| Astro Primitive | `@starwind-ui/astro/radio-group` | `RadioGroup`, `RadioGroupRoot` |
| React Primitive | `@starwind-ui/react/radio-group` | `RadioGroup`, `RadioGroupRoot` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `RadioGroup` |
| runtime-factory | `createRadioGroup` |
| part | `RadioGroup.Root` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.1
- Synchronized vendored React Radio Group state after accepted Runtime transitions and external state changes.
### v0.1.0
- Introduced grouped radio ownership, roving keyboard focus, value changes, and form participation.

---

Source: [https://starwind.dev/docs/primitives/scroll-area/](https://starwind.dev/docs/primitives/scroll-area/) · [Markdown](https://starwind.dev/docs/primitives/scroll-area.md)

# Scroll Area Primitive

Scroll Area is a Starwind Runtime primitive in the viewport-measurement contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render ScrollArea anatomy with the Runtime wiring included.
```astro
---
import { ScrollArea } from "@starwind-ui/astro/scroll-area";
---

<ScrollArea.Root>
  <ScrollArea.Viewport>
    <ScrollArea.Content>Scrollable content</ScrollArea.Content>
  </ScrollArea.Viewport>
  <ScrollArea.Scrollbar>
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
  <ScrollArea.Corner />
</ScrollArea.Root>
```

### React
Use the React primitive adapter when ScrollArea state participates in React rendering.
```tsx
import { ScrollArea } from "@starwind-ui/react/scroll-area";

export function Example() {
  return (
    <ScrollArea.Root>
      <ScrollArea.Viewport>
        <ScrollArea.Content>Scrollable content</ScrollArea.Content>
      </ScrollArea.Viewport>
      <ScrollArea.Scrollbar>
        <ScrollArea.Thumb />
      </ScrollArea.Scrollbar>
      <ScrollArea.Corner />
    </ScrollArea.Root>
  );
}
```

### HTML
Render the ScrollArea data-sw-* contract yourself, then initialize createScrollArea.
```html
<div data-sw-scroll-area role="presentation">
  <div data-sw-scroll-area-viewport role="presentation" tabindex="-1" style="overflow: scroll;">
    <div data-sw-scroll-area-content role="presentation">Scrollable content</div>
  </div>
  <div data-sw-scroll-area-scrollbar aria-hidden="true">
    <div data-sw-scroll-area-thumb></div>
  </div>
  <div data-sw-scroll-area-corner aria-hidden="true"></div>
</div>

const root = document.querySelector("[data-sw-scroll-area]");
  if (root) {
    createScrollArea(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Scroll Area Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area` |
| Role | `presentation` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| overflowEdgeThreshold | `number \| Partial<{<br>  xStart: number;<br>  xEnd: number;<br>  yStart: number;<br>  yEnd: number;<br>}>` | - | option | Configures the overflow edge threshold option for the Root part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-overflow-edge-threshold` | prop | - | Reflects the overflow edge threshold prop on the Root part. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area`, `data-overflow-edge-threshold`, `role` | The root needs a stable discovery marker and optional overflow edge threshold before measurement starts. |

### Viewport
The visible viewport for Scroll Area content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area-viewport` |
| Role | `presentation` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area-viewport`, `role`, `tabindex`, `style` | The viewport must be scrollable and initially unfocusable until runtime detects overflow. |

### Content
The content container rendered by Scroll Area.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area-content` |
| Role | `presentation` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area-content` | runtime | - | Marks the Content part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| content | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area-content`, `role` | The content element is the resize and mutation target for scroll measurement. |

### Scrollbar
A scrollbar used to scroll Scroll Area content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area-scrollbar` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| keepMounted | `boolean` | false | rendering | Keeps the Scrollbar part in the DOM when hidden. | - |
| orientation | `"horizontal" \| "vertical"` | "vertical" | option | Sets the Scroll Area orientation. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area-scrollbar` | runtime | - | Marks the Scrollbar part so Starwind Runtime can find it. |
| `data-keep-mounted` | prop | - | Reflects the keep mounted prop on the Scrollbar part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Scrollbar part. |
#### Refs
| Part | Public |
| --- | --- |
| scrollbar | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area-scrollbar`, `data-keep-mounted`, `data-orientation`, `aria-hidden` | Scrollbars need orientation and keep-mounted hints before the runtime measures overflow. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | keepMounted |

### Thumb
The draggable thumb for Scroll Area.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area-thumb` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area-thumb` | runtime | - | Marks the Thumb part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| thumb | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area-thumb` | Thumbs are measured and positioned by the runtime for each scrollbar. |

### Corner
The corner where Scroll Area scrollbars meet.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area-corner` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area-corner` | runtime | - | Marks the Corner part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| corner | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area-corner`, `aria-hidden` | The corner is presentation-only and sized by the runtime when both scrollbars are present. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createScrollArea`](/docs/runtime/#create-scroll-area) |
| Import | `@starwind-ui/runtime/scroll-area` |
| Root part | root |
| Option props | overflowEdgeThreshold |
| Option lifecycles | overflowEdgeThreshold: refresh-required |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Scroll Area](/docs/components/scroll-area/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/scroll-area` | `createScrollArea` |
| Astro Primitive | `@starwind-ui/astro/scroll-area` | `ScrollArea`, `ScrollAreaRoot`, `ScrollAreaViewport`, `ScrollAreaContent`, `ScrollAreaScrollbar`, `ScrollAreaThumb`, `ScrollAreaCorner` |
| React Primitive | `@starwind-ui/react/scroll-area` | `ScrollArea`, `ScrollAreaRoot`, `ScrollAreaViewport`, `ScrollAreaContent`, `ScrollAreaScrollbar`, `ScrollAreaThumb`, `ScrollAreaCorner` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `ScrollArea` |
| runtime-factory | `createScrollArea` |
| part | `ScrollArea.Root` |
| part | `ScrollArea.Viewport` |
| part | `ScrollArea.Content` |
| part | `ScrollArea.Scrollbar` |
| part | `ScrollArea.Thumb` |
| part | `ScrollArea.Corner` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced viewport measurement and synchronized scrollbar, thumb, and corner anatomy.

---

Source: [https://starwind.dev/docs/primitives/select/](https://starwind.dev/docs/primitives/select/) · [Markdown](https://starwind.dev/docs/primitives/select.md)

# Select Primitive

Select is a Starwind Runtime primitive in the floating-value-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Select anatomy with the Runtime wiring included.
```astro
---
import { Select } from "@starwind-ui/astro/select";
---

<Select.Root>
  <Select.Label>Choose a framework</Select.Label>
  <Select.Trigger>
    <Select.Value>Astro</Select.Value>
    <Select.Icon>v</Select.Icon>
  </Select.Trigger>
  <Select.Positioner>
    <Select.Popup />
  </Select.Positioner>
</Select.Root>
```

### React
Use the React primitive adapter when Select state participates in React rendering.
```tsx
import { Select } from "@starwind-ui/react/select";

export function Example() {
  return (
    <Select.Root>
      <Select.Label>Choose a framework</Select.Label>
      <Select.Trigger>
        <Select.Value>Astro</Select.Value>
        <Select.Icon>v</Select.Icon>
      </Select.Trigger>
      <Select.Positioner>
        <Select.Popup />
      </Select.Positioner>
    </Select.Root>
  );
}
```

### HTML
Render the Select data-sw-* contract yourself, then initialize createSelect.
```html
<div data-sw-select>
  <div data-sw-select-label>Choose a framework</div>
  <button data-sw-select-trigger role="combobox" aria-haspopup="listbox">
    <span data-sw-select-value>Astro</span>
    <span data-sw-select-icon aria-hidden="true">v</span>
  </button>
  <div data-sw-select-positioner>
    <div data-sw-select-popup role="listbox" hidden tabindex="-1">
      <div data-sw-select-list>
        <div data-sw-select-item role="option" data-value="astro">
          <span data-sw-select-item-text>Astro</span>
          <span data-sw-select-item-indicator aria-hidden="true" hidden></span>
        </div>
      </div>
    </div>
  </div>
</div>

const root = document.querySelector("[data-sw-select]");
  if (root) {
    createSelect(root);
  }
</script>
```
## Positioning
Select positions its popup from the trigger. Keep the `Positioner` and `Popup` parts near the trigger in source order so the relationship stays readable, then let the Runtime handle placement, collision, and open-state updates after hydration.

## Examples
### Positioned Select
Render Select with a positioned popup across Astro, React, and HTML surfaces.
#### Astro
```astro
---
import { Select } from "@starwind-ui/astro/select";
---

<Select.Root defaultValue="astro">
  <Select.Label>Framework</Select.Label>
  <Select.Trigger>
    <Select.Value>Astro</Select.Value>
    <Select.Icon>v</Select.Icon>
  </Select.Trigger>
  <Select.Positioner>
    <Select.Popup>
      <Select.List>
        <Select.Item value="astro">
          <Select.ItemText>Astro</Select.ItemText>
          <Select.ItemIndicator />
        </Select.Item>
        <Select.Item value="react">
          <Select.ItemText>React</Select.ItemText>
          <Select.ItemIndicator />
        </Select.Item>
      </Select.List>
    </Select.Popup>
  </Select.Positioner>
</Select.Root>

```

#### React
```tsx
import { Select } from "@starwind-ui/react/select";

export function Example() {
  return (
    <Select.Root defaultValue="astro">
      <Select.Label>Framework</Select.Label>
      <Select.Trigger>
        <Select.Value>Astro</Select.Value>
        <Select.Icon>v</Select.Icon>
      </Select.Trigger>
      <Select.Positioner>
        <Select.Popup>
          <Select.List>
            <Select.Item value="astro">
              <Select.ItemText>Astro</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
            <Select.Item value="react">
              <Select.ItemText>React</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
          </Select.List>
        </Select.Popup>
      </Select.Positioner>
    </Select.Root>
  );
}

```

#### HTML
```html
<div data-sw-select data-default-value="astro">
  <span data-sw-select-label>Framework</span>
  <button data-sw-select-trigger type="button">
    <span data-sw-select-value>Astro</span>
    <span data-sw-select-icon>v</span>
  </button>
  <div data-sw-select-positioner>
    <div data-sw-select-popup>
      <div data-sw-select-list>
        <div data-sw-select-item data-value="astro">
          <span data-sw-select-item-text>Astro</span>
          <span data-sw-select-item-indicator></span>
        </div>
        <div data-sw-select-item data-value="react">
          <span data-sw-select-item-text>React</span>
          <span data-sw-select-item-indicator></span>
        </div>
      </div>
    </div>
  </div>
</div>

const root = document.querySelector("[data-sw-select]");
  if (root) {
    createSelect(root);
  }
</script>

```
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | trigger |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, alignOffset, avoidCollisions, alignItemWithTrigger |
## API Reference
### Root
The main element that owns the Select Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Select is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | - | control | Sets whether Select starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| value | `string \| null` | - | control | Controls the current Select value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `string \| null` | - | control | Sets the initial Select value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| autoComplete | `string` | - | option | Sets the native autocomplete behavior. | - |
| disabled | `boolean` | - | option | Disables the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| highlightItemOnHover | `boolean` | true | option | Highlights Select items when the pointer moves over them. | - |
| modal | `boolean` | true | option | Makes Select behave as a modal overlay. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| readOnly | `boolean` | false | option | Marks the control as read-only. | - |
| required | `boolean` | - | option | Marks the form control as required. | - |
| onOpenChange | `(open: boolean, details: SelectOpenChangeDetails) => void` | - | callback | Runs when Select opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| onValueChange | `(value: string \| null, details: SelectValueChangeDetails) => void` | - | callback | Runs when the Select value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Root part. |
| `data-autocomplete` | prop | - | Reflects the autocomplete prop on the Root part. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-highlight-item-on-hover` | prop | - | Reflects the highlight item on hover prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Select is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| value | `string \| null` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Select value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | SelectOpenChangeDetails | before-state-commit | Yes | Fires when Select opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| valueChange | onValueChange | starwind:value-change | value: `string \| null` | SelectValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Select. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | - | Yes | Opens or closes Select from Runtime code. |
| `setValue` | state: value | - | Yes | Updates the current Select value from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Form
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | input (hidden) |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Label
Text label associated with Select.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |

### Trigger
The control that opens, closes, or targets the Select content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-select-trigger` |
| Role | `combobox` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `role`, `aria-haspopup`, `aria-expanded`, `aria-readonly`, `data-state` | Keyboard and assistive technology affordances must be present before hydration. |

### Value
Displays the current Select value.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-select-value` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-value` | runtime | - | Marks the Value part so Starwind Runtime can find it. |

### Icon
Decorative icon rendered by Select.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-select-icon` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-icon` | runtime | - | Marks the Icon part so Starwind Runtime can find it. |

### Input
The native input synchronized by Select.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-select-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | input (hidden) |

### Portal
Moves Select overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |

### Positioner
Positions the Select content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Select content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Select content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Select content and its trigger. | - |
| alignOffset | `number` | 0 | option | Adjusts the cross-axis alignment offset for Select content. | - |
| avoidCollisions | `boolean` | true | option | Allows Select content to shift or flip to stay visible. | - |
| alignItemWithTrigger | `boolean` | true | option | Configures the align item with trigger option for the Positioner part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-align-offset` | prop | - | Reflects the align offset prop on the Positioner part. |
| `data-align-item-with-trigger` | prop | - | Reflects the align item with trigger prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |

### Popup
The floating content container for Select.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-popup` |
| Role | `listbox` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Select content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Select content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Select content and its trigger. | - |
| alignOffset | `number` | 0 | option | Adjusts the cross-axis alignment offset for Select content. | - |
| avoidCollisions | `boolean` | true | option | Allows Select content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-align-offset` | prop | - | Reflects the align offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `role`, `hidden`, `data-state`, `data-side`, `data-align` | Floating content starts closed and is positioned by the runtime once opened. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### List
The list of selectable Select items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-list` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-list` | runtime | - | Marks the List part so Starwind Runtime can find it. |

### Group
Groups related Select items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-group` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-group` | runtime | - | Marks the Group part so Starwind Runtime can find it. |

### Group Label
Labels a group of Select items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-group-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-group-label` | runtime | - | Marks the Group Label part so Starwind Runtime can find it. |

### Item
An interactive item inside the Select collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-item` |
| Role | `option` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Item part. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |

### Item Text
Text content for a Select item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-select-item-text` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-item-text` | runtime | - | Marks the Item Text part so Starwind Runtime can find it. |

### Item Indicator
Shows the selected state for a Select item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-select-item-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-item-indicator` | runtime | - | Marks the Item Indicator part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Item Indicator part. |
| `data-hidden` | state | - | Reflects the hidden state on the Item Indicator part. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Separator
Separates groups of Select items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-separator` |
| Role | `separator` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-separator` | runtime | - | Marks the Separator part so Starwind Runtime can find it. |

### Scroll Up Arrow
Scrolls Select options upward.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-scroll-up-arrow` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-scroll-up-arrow` | runtime | - | Marks the Scroll Up Arrow part so Starwind Runtime can find it. |

### Scroll Down Arrow
Scrolls Select options downward.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-scroll-down-arrow` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-scroll-down-arrow` | runtime | - | Marks the Scroll Down Arrow part so Starwind Runtime can find it. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createSelect`](/docs/runtime/#create-select) |
| Import | `@starwind-ui/runtime/select` |
| Root part | root |
| Option props | autoComplete, defaultOpen, defaultValue, disabled, form, highlightItemOnHover, modal, open, readOnly, value |
| Option lifecycles | autoComplete: constructor-only, defaultOpen: constructor-only, defaultValue: constructor-only, disabled: constructor-only, form: constructor-only, highlightItemOnHover: constructor-only, modal: constructor-only, open: setter-backed, readOnly: constructor-only, value: setter-backed |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | input (hidden) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Select](/docs/components/select/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/select` | `createSelect` |
| Astro Primitive | `@starwind-ui/astro/select` | `Select`, `SelectRoot`, `SelectLabel`, `SelectTrigger`, `SelectValue`, `SelectIcon`, `SelectPortal`, `SelectPositioner`, `SelectPopup`, `SelectGroup`, `SelectGroupLabel`, `SelectItem`, `SelectItemText`, `SelectItemIndicator`, `SelectSeparator`, `SelectScrollUpArrow`, `SelectScrollDownArrow` |
| React Primitive | `@starwind-ui/react/select` | `Select`, `SelectRoot`, `SelectLabel`, `SelectTrigger`, `SelectValue`, `SelectIcon`, `SelectPortal`, `SelectPositioner`, `SelectPopup`, `SelectGroup`, `SelectGroupLabel`, `SelectItem`, `SelectItemText`, `SelectItemIndicator`, `SelectSeparator`, `SelectScrollUpArrow`, `SelectScrollDownArrow` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Select` |
| runtime-factory | `createSelect` |
| part | `Select.Root` |
| part | `Select.Label` |
| part | `Select.Trigger` |
| part | `Select.Value` |
| part | `Select.Icon` |
| part | `Select.Portal` |
| part | `Select.Positioner` |
| part | `Select.Popup` |
| part | `Select.Group` |
| part | `Select.GroupLabel` |
| part | `Select.Item` |
| part | `Select.ItemText` |
| part | `Select.ItemIndicator` |
| part | `Select.Separator` |
| part | `Select.ScrollUpArrow` |
| part | `Select.ScrollDownArrow` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.4
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
- Initialized React Select from silent programmatic value commands so composed format controls show their configured value before interaction.
- Preserved selected-value styling when React Select triggers are composed inside Color Picker format controls.
### v0.1.3
- Preserved intentionally empty item labels and their lazy hidden form values in React.
### v0.1.2
- Deferred React controller initialization and improved closed-mount behavior while preserving state and form synchronization.
### v0.1.1
- Enabled modal background-scroll locking by default while the listbox is open.
### v0.1.0
- Introduced selection state, keyboard navigation, floating listbox placement, events, and form participation.

---

Source: [https://starwind.dev/docs/primitives/sidebar/](https://starwind.dev/docs/primitives/sidebar/) · [Markdown](https://starwind.dev/docs/primitives/sidebar.md)

# Sidebar Primitive

Sidebar is a Starwind Runtime primitive in the presence-disclosure-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Sidebar anatomy with the Runtime wiring included.
```astro
---
import { Sidebar } from "@starwind-ui/astro/sidebar";
---

<Sidebar.Provider>
  <Sidebar.Sidebar>
    <Sidebar.MenuButton>Dashboard</Sidebar.MenuButton>
  </Sidebar.Sidebar>
  <Sidebar.Trigger>Toggle sidebar</Sidebar.Trigger>
  <Sidebar.Rail />
</Sidebar.Provider>
```

### React
Use the React primitive adapter when Sidebar state participates in React rendering.
```tsx
import { Sidebar } from "@starwind-ui/react/sidebar";

export function Example() {
  return (
    <Sidebar.Provider>
      <Sidebar.Sidebar>
        <Sidebar.MenuButton>Dashboard</Sidebar.MenuButton>
      </Sidebar.Sidebar>
      <Sidebar.Trigger>Toggle sidebar</Sidebar.Trigger>
      <Sidebar.Rail />
    </Sidebar.Provider>
  );
}
```

### HTML
Render the Sidebar data-sw-* contract yourself, then initialize createSidebarController.
```html
<div data-sw-sidebar-provider>
  <div data-sw-sidebar>
    <button data-sw-sidebar-menu-button>Dashboard</button>
  </div>
  <button data-sw-sidebar-trigger type="button">Toggle sidebar</button>
  <button data-sw-sidebar-rail type="button" tabindex="-1"></button>
</div>

const root = document.querySelector("[data-sw-sidebar-provider]");
  if (root) {
    createSidebarController(root);
  }
</script>
```
## API Reference
### Provider
Provides shared Sidebar state to nested parts.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-sidebar-provider` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Sidebar is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for state changes.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:sidebar-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | true | control | Sets whether Sidebar starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for state changes.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:sidebar-change, and call setOpen for later updates. |
| mobileOpen | `boolean` | - | control | Controls the mobile open state for Sidebar. | **React:** Use mobileOpen for controlled state and defaultMobileOpen for default state, and onMobileOpenChange for state changes.<br>**Astro:** Use mobileOpen or defaultMobileOpen for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.<br>**Runtime / HTML:** Use data-default-mobile-open for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates. |
| defaultMobileOpen | `boolean` | false | control | Controls the default mobile open state for Sidebar. | **React:** Use mobileOpen for controlled state and defaultMobileOpen for default state, and onMobileOpenChange for state changes.<br>**Astro:** Use mobileOpen or defaultMobileOpen for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.<br>**Runtime / HTML:** Use data-default-mobile-open for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates. |
| keyboardShortcut | `string` | "b" | option | Configures the keyboard shortcut option for the Provider part. | - |
| mobileQuery | `string` | "(max-width: 767.98px)" | option | Configures the mobile query option for the Provider part. | - |
| persistOpen | `boolean` | false | option | Configures the persist open option for the Provider part. | - |
| persistenceKey | `string` | "starwind-sidebar-open" | option | Configures the persistence key option for the Provider part. | - |
| persistenceStorage | `SidebarPersistenceStorage` | "localStorage" | option | Configures the persistence storage option for the Provider part. | - |
| persistenceMaxAge | `number` | 604800 | option | Configures the persistence max age option for the Provider part. | - |
| onOpenChange | `(open: boolean, details: SidebarOpenChangeDetails) => void` | - | callback | Runs when Sidebar opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for state changes.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:sidebar-change, and call setOpen for later updates. |
| onMobileOpenChange | `(open: boolean, details: SidebarMobileOpenChangeDetails) => void` | - | callback | Runs when on mobile open change changes for Sidebar. | **React:** Use mobileOpen for controlled state and defaultMobileOpen for default state, and onMobileOpenChange for state changes.<br>**Astro:** Use mobileOpen or defaultMobileOpen for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.<br>**Runtime / HTML:** Use data-default-mobile-open for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-sidebar-provider` | runtime | - | Marks the Provider part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Provider part. |
| `data-default-mobile-open` | prop | - | Reflects the default mobile open prop on the Provider part. |
| `data-state` | state | - | Reflects the current state on the Provider part. |
| `data-mobile-open` | state | - | Reflects the mobile open state on the Provider part. |
| `data-keyboard-shortcut` | prop | - | Reflects the keyboard shortcut prop on the Provider part. |
| `data-mobile-query` | prop | - | Reflects the mobile query prop on the Provider part. |
| `data-persist-open` | prop | - | Reflects the persist open prop on the Provider part. |
| `data-persistence-key` | prop | - | Reflects the persistence key prop on the Provider part. |
| `data-persistence-storage` | prop | - | Reflects the persistence storage prop on the Provider part. |
| `data-persistence-max-age` | prop | - | Reflects the persistence max age prop on the Provider part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Sidebar is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for state changes.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:sidebar-change, and call setOpen for later updates. |
| mobileOpen | `boolean` | mobileOpen | defaultMobileOpen | `data-default-mobile-open` | `getMobileOpen` | `setMobileOpen` | Tracks whether the mobile Sidebar panel is open. | **React:** Use mobileOpen for controlled state and defaultMobileOpen for default state, and onMobileOpenChange for state changes.<br>**Astro:** Use mobileOpen or defaultMobileOpen for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.<br>**Runtime / HTML:** Use data-default-mobile-open for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:sidebar-change | open: `boolean` | SidebarOpenChangeDetails | - | - | Fires when Sidebar opens or closes. | - |
| mobileOpenChange | onMobileOpenChange | starwind:sidebar-mobile-change | open: `boolean` | SidebarMobileOpenChangeDetails | - | - | Fires when the mobile panel opens or closes for Sidebar. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Sidebar from Runtime code. |
| `setMobileOpen` | state: mobileOpen | emit: false | Yes | Opens or closes the mobile Sidebar panel from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| provider | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-sidebar-provider`, `data-default-open`, `data-default-mobile-open`, `data-state`, `data-mobile-open`, `data-keyboard-shortcut`, `data-mobile-query`, `data-persist-open`, `data-persistence-key`, `data-persistence-storage`, `data-persistence-max-age` | The provider needs initial desktop/mobile state, shortcut, media query, and opt-in persistence markers before hydration. |

### Sidebar
The visible sidebar panel for Sidebar.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-sidebar` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"left" \| "right"` | "left" | attribute | Sets the preferred side for Sidebar content. | - |
| variant | `"sidebar" \| "floating" \| "inset"` | "sidebar" | attribute | Selects the visual variant for the Sidebar part. | - |
| collapsible | `"offcanvas" \| "icon"` | "offcanvas" | attribute | Allows all Sidebar items to be collapsed. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-sidebar` | runtime | - | Marks the Sidebar part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Sidebar part. |
| `data-collapsible` | state | - | Reflects the collapsible state on the Sidebar part. |
| `data-collapsible-mode` | prop | - | Reflects the collapsible mode prop on the Sidebar part. |
| `data-variant` | prop | - | Reflects the variant prop on the Sidebar part. |
| `data-side` | prop | - | Reflects the side prop on the Sidebar part. |
#### Refs
| Part | Public |
| --- | --- |
| sidebar | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-sidebar`, `data-state`, `data-collapsible`, `data-collapsible-mode`, `data-variant`, `data-side` | The desktop sidebar uses initial state, collapsible mode, variant, and side attributes for layout before hydration. |

### Trigger
The control that opens, closes, or targets the Sidebar content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-sidebar-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | false | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-sidebar-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-sidebar-trigger`, `type`, `aria-expanded`, `data-state` | Triggers need button semantics, expanded state, and discovery before listeners attach. |

### Rail
A compact control for resizing or toggling Sidebar.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-sidebar-rail` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-sidebar-rail` | runtime | - | Marks the Rail part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Rail part. |
#### Refs
| Part | Public |
| --- | --- |
| rail | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-sidebar-rail`, `type`, `aria-expanded`, `data-state`, `tabindex` | The resize rail acts as an unfocusable toggle target with stable expanded state before hydration. |

### Menu Button
A menu-style button rendered inside Sidebar.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-sidebar-menu-button` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | false | rendering | Merges behavior onto your child element instead of rendering the default Menu Button element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-sidebar-menu-button` | runtime | - | Marks the Menu Button part so Starwind Runtime can find it. |
| `data-sidebar-state` | state | - | Reflects the sidebar state on the Menu Button part. |
#### Refs
| Part | Public |
| --- | --- |
| menuButton | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| menuButton | aria, className, data, events, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-sidebar-menu-button`, `data-sidebar-state` | Menu buttons receive the current sidebar state for icon-mode tooltip styling. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createSidebarController`](/docs/runtime/#create-sidebar-controller) |
| Import | `@starwind-ui/runtime/sidebar` |
| Root part | provider |
| Option props | defaultMobileOpen, defaultOpen, keyboardShortcut, mobileOpen, mobileQuery, onMobileOpenChange, onOpenChange, open, persistOpen, persistenceKey, persistenceMaxAge, persistenceStorage |
| Option lifecycles | defaultMobileOpen: constructor-only, defaultOpen: constructor-only, keyboardShortcut: constructor-only, mobileOpen: setter-backed, mobileQuery: constructor-only, onMobileOpenChange: constructor-only, onOpenChange: constructor-only, open: setter-backed, persistOpen: constructor-only, persistenceKey: constructor-only, persistenceMaxAge: constructor-only, persistenceStorage: constructor-only |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Sidebar](/docs/components/sidebar/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/sidebar` | `createSidebarController` |
| Astro Primitive | `@starwind-ui/astro/sidebar` | `Sidebar`, `SidebarProvider`, `SidebarSidebar`, `SidebarTrigger`, `SidebarRail`, `SidebarMenuButton` |
| React Primitive | `@starwind-ui/react/sidebar` | `Sidebar`, `SidebarProvider`, `SidebarSidebar`, `SidebarTrigger`, `SidebarRail`, `SidebarMenuButton` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Sidebar` |
| runtime-factory | `createSidebarController` |
| part | `Sidebar.Provider` |
| part | `Sidebar.Sidebar` |
| part | `Sidebar.Trigger` |
| part | `Sidebar.Rail` |
| part | `Sidebar.MenuButton` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced provider-owned expanded, collapsed, and mobile state with coordinated controls and panels.

---

Source: [https://starwind.dev/docs/primitives/slider/](https://starwind.dev/docs/primitives/slider/) · [Markdown](https://starwind.dev/docs/primitives/slider.md)

# Slider Primitive

Slider is a Starwind Runtime primitive in the form-value-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Slider anatomy with the Runtime wiring included.
```astro
---
import { Slider } from "@starwind-ui/astro/slider";
---

<Slider.Root>
  <Slider.Label>Volume</Slider.Label>
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>
```

### React
Use the React primitive adapter when Slider state participates in React rendering.
```tsx
import { Slider } from "@starwind-ui/react/slider";

export function Example() {
  return (
    <Slider.Root>
      <Slider.Label>Volume</Slider.Label>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  );
}
```

### HTML
Render the Slider data-sw-* contract yourself, then initialize createSlider.
```html
<div data-sw-slider role="group">
  <span data-sw-slider-label>Volume</span>
  <div data-sw-slider-control>
    <div data-sw-slider-track>
      <div data-sw-slider-indicator></div>
      <div data-sw-slider-thumb></div>
    </div>
  </div>
</div>

const root = document.querySelector("[data-sw-slider]");
  if (root) {
    createSlider(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Slider Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-slider` |
| Role | `group` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `SliderValue` | - | control | Controls the current Slider value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `SliderValue` | 0 | control | Sets the initial Slider value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| largeStep | `number` | 10 | option | Configures the large step option for the Root part. | - |
| max | `number` | 100 | option | Configures the max option for the Root part. | - |
| min | `number` | 0 | option | Configures the min option for the Root part. | - |
| minStepsBetweenValues | `number` | 0 | option | Configures the min steps between values option for the Root part. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| orientation | `SliderOrientation` | "horizontal" | option | Sets the Slider orientation. | - |
| step | `number` | 1 | option | Configures the step option for the Root part. | - |
| onValueChange | `(value: SliderValue, details: SliderValueChangeDetails) => void` | - | callback | Runs when the Slider value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| onValueCommitted | `(value: SliderValue, details: SliderValueCommitDetails) => void` | - | callback | Runs when on value committed changes for Slider. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-large-step` | prop | - | Reflects the large step prop on the Root part. |
| `data-max` | prop | - | Reflects the max prop on the Root part. |
| `data-min` | prop | - | Reflects the min prop on the Root part. |
| `data-min-steps-between-values` | prop | - | Reflects the min steps between values prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Root part. |
| `data-step` | prop | - | Reflects the step prop on the Root part. |
| `data-value` | state | - | Reflects the value state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `SliderValue` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Slider value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `SliderValue` | SliderValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Slider. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| valueCommitted | onValueCommitted | starwind:value-committed | value: `SliderValue` | SliderValueCommitDetails | - | - | Fires when the user commits the value for Slider. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Slider value from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Slider is disabled from Runtime code. |
| `setName` | prop: name | - | No | Updates the Slider form field name from Runtime code. |
| `setOptions` | props: form, largeStep, max, min, minStepsBetweenValues, orientation, step | - | No | Updates Runtime options after initialization. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-slider`, `role`, `data-default-value`, `data-min`, `data-max`, `data-step`, `data-large-step`, `data-min-steps-between-values`, `data-orientation`, `data-value` | Range values and orientation styling must be present before controller hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, name, value |
| Hidden input | input (range) |

### Control
Groups the interactive controls for Slider.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-slider-control` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-control` | runtime | - | Marks the Control part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| control | Yes |

### Track
The track that contains the Slider range.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-slider-track` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-track` | runtime | - | Marks the Track part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| track | Yes |

### Indicator
Visual state indicator rendered by Slider.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-slider-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-indicator` | runtime | - | Marks the Indicator part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| indicator | Yes |

### Label
Text label associated with Slider.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-slider-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-slider-label` | Visible labels can be linked to slider thumbs by the runtime after hydration. |

### Thumb
The draggable thumb for Slider.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-slider-thumb` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| index | `number` | - | attribute | Sets the index attribute on the Thumb part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-thumb` | runtime | - | Marks the Thumb part so Starwind Runtime can find it. |
| `data-index` | prop | - | Reflects the index prop on the Thumb part. |
#### Refs
| Part | Public |
| --- | --- |
| thumb | Yes |

### Input
The native input synchronized by Slider.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-slider-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-slider-input`, `type`, `aria-hidden`, `tabIndex` | Each thumb needs a nested range input placeholder so the runtime can wire form submission and input-change behavior. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, name, value |
| Hidden input | input (range) |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createSlider`](/docs/runtime/#create-slider) |
| Import | `@starwind-ui/runtime/slider` |
| Root part | root |
| Option props | defaultValue, disabled, form, largeStep, max, min, minStepsBetweenValues, name, orientation, step, value |
| Option lifecycles | disabled: setter-backed, form: setter-backed, largeStep: setter-backed, max: setter-backed, min: setter-backed, minStepsBetweenValues: setter-backed, name: setter-backed, orientation: setter-backed, step: setter-backed, value: setter-backed |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, name, value |
| Hidden input | input (range) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Slider](/docs/components/slider/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/slider` | `createSlider` |
| Astro Primitive | `@starwind-ui/astro/slider` | `Slider`, `SliderRoot`, `SliderControl`, `SliderTrack`, `SliderIndicator`, `SliderLabel`, `SliderThumb` |
| React Primitive | `@starwind-ui/react/slider` | `Slider`, `SliderRoot`, `SliderControl`, `SliderTrack`, `SliderIndicator`, `SliderLabel`, `SliderThumb` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Slider` |
| runtime-factory | `createSlider` |
| part | `Slider.Root` |
| part | `Slider.Control` |
| part | `Slider.Track` |
| part | `Slider.Indicator` |
| part | `Slider.Label` |
| part | `Slider.Thumb` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced single and multi-value state, pointer dragging, keyboard interaction, and form participation.

---

Source: [https://starwind.dev/docs/primitives/switch/](https://starwind.dev/docs/primitives/switch/) · [Markdown](https://starwind.dev/docs/primitives/switch.md)

# Switch Primitive

Switch is a Starwind Runtime primitive in the single-boolean-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Switch anatomy with the Runtime wiring included.
```astro
---
import { Switch } from "@starwind-ui/astro/switch";
---

<Switch.Root>
  <Switch.Thumb />
</Switch.Root>
```

### React
Use the React primitive adapter when Switch state participates in React rendering.
```tsx
import { Switch } from "@starwind-ui/react/switch";

export function Example() {
  return (
    <Switch.Root>
      <Switch.Thumb />
    </Switch.Root>
  );
}
```

### HTML
Render the Switch data-sw-* contract yourself, then initialize createSwitch.
```html
<span data-sw-switch role="switch">
  <span data-sw-switch-thumb></span>
  <input data-sw-switch-input type="checkbox" aria-hidden="true" tabindex="-1" />
</span>

const root = document.querySelector("[data-sw-switch]");
  if (root) {
    createSwitch(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Switch Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-switch` |
| Role | `switch` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| checked | `boolean` | - | control | Controls whether Switch is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| defaultChecked | `boolean` | false | control | Sets whether Switch starts checked for uncontrolled usage. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| id | `string` | - | option | Sets the id used by the associated native control. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| nativeButton | `boolean` | false | rendering | Renders the control as a native button element. | - |
| readOnly | `boolean` | false | option | Marks the control as read-only. | - |
| required | `boolean` | false | option | Marks the form control as required. | - |
| uncheckedValue | `string` | - | option | Sets the value submitted when the checkbox is unchecked. | - |
| value | `string` | - | option | Controls the current Switch value. | - |
| onCheckedChange | `(checked: boolean, details: SwitchCheckedChangeDetails) => void` | - | callback | Runs when the Switch checked state changes. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-switch` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-checked` | state | - | Reflects the checked state on the Root part. |
| `data-default-checked` | prop | - | Reflects the default checked prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-filled` | state | - | Reflects the filled state on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-id` | prop | - | Reflects the id prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
| `data-unchecked` | state | - | Reflects the unchecked state on the Root part. |
| `data-unchecked-value` | prop | - | Reflects the unchecked value prop on the Root part. |
| `data-value` | prop | - | Reflects the value prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | `getChecked` | `setChecked` | Tracks whether Switch is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checkedChange | onCheckedChange | starwind:checked-change | checked: `boolean` | SwitchCheckedChangeDetails | before-state-commit | Yes | Fires when the checked state changes for Switch. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setChecked` | state: checked | emit: false | Yes | Updates whether Switch is checked from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Switch is disabled from Runtime code. |
| `setFormOptions` | props: form, name, required, uncheckedValue, value | - | No | Updates Switch form-related options from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-switch`, `role`, `aria-checked`, `data-checked`, `data-unchecked`, `data-default-checked`, `data-disabled` | The visible switch needs ARIA and state styling before the controller attaches. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |

### Thumb
The draggable thumb for Switch.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-switch-thumb` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-switch-thumb` | runtime | - | Marks the Thumb part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| thumb | Yes |

### Input
The native input synchronized by Switch.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-switch-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-switch-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| input | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-switch-input` | The runtime needs the sibling input placeholder so it can attach form state after hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |

### Unchecked Input
The hidden native input used when Switch submits an unchecked value.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-switch-unchecked-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-switch-unchecked-input` | runtime | - | Marks the Unchecked Input part so Starwind Runtime can find it. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createSwitch`](/docs/runtime/#create-switch) |
| Import | `@starwind-ui/runtime/switch` |
| Root part | root |
| Option props | checked, defaultChecked, disabled, form, id, name, readOnly, required, uncheckedValue, value |
| Option lifecycles | - |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Switch](/docs/components/switch/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/switch` | `createSwitch` |
| Astro Primitive | `@starwind-ui/astro/switch` | `Switch`, `SwitchRoot`, `SwitchThumb` |
| React Primitive | `@starwind-ui/react/switch` | `Switch`, `SwitchRoot`, `SwitchThumb` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Switch` |
| runtime-factory | `createSwitch` |
| part | `Switch.Root` |
| part | `Switch.Thumb` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
- Preserved native form association when React reconciles controlled checked state.
### v0.1.0
- Introduced checked state, form participation, and checked-change events.

---

Source: [https://starwind.dev/docs/primitives/tabs/](https://starwind.dev/docs/primitives/tabs/) · [Markdown](https://starwind.dev/docs/primitives/tabs.md)

# Tabs Primitive

Tabs is a Starwind Runtime primitive in the controlled-value-group contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Tabs anatomy with the Runtime wiring included.
```astro
---
import { Tabs } from "@starwind-ui/astro/tabs";
---

<Tabs.Root defaultValue="account">
  <Tabs.List>
    <Tabs.Tab value="account">Account</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="account">Account settings</Tabs.Panel>
</Tabs.Root>
```

### React
Use the React primitive adapter when Tabs state participates in React rendering.
```tsx
import { Tabs } from "@starwind-ui/react/tabs";

export function Example() {
  return (
    <Tabs.Root defaultValue="account">
      <Tabs.List>
        <Tabs.Tab value="account">Account</Tabs.Tab>
      </Tabs.List>
      <Tabs.Panel value="account">Account settings</Tabs.Panel>
    </Tabs.Root>
  );
}
```

### HTML
Render the Tabs data-sw-* contract yourself, then initialize createTabs.
```html
<div data-sw-tabs data-default-value="account">
  <div data-sw-tabs-list role="tablist">
    <button data-sw-tabs-tab role="tab" type="button" data-value="account">Account</button>
  </div>
  <div data-sw-tabs-panel role="tabpanel" hidden data-value="account">Account settings</div>
</div>

const root = document.querySelector("[data-sw-tabs]");
  if (root) {
    createTabs(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Tabs Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-tabs` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `TabsValue` | - | control | Controls the current Tabs value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `TabsValue` | - | control | Sets the initial Tabs value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| orientation | `TabsOrientation` | "horizontal" | option | Sets the Tabs orientation. | - |
| syncKey | `string` | - | option | Configures the sync key option for the Root part. | - |
| onValueChange | `(value: TabsValue, details: TabsValueChangeDetails) => void` | - | callback | Runs when the Tabs value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tabs` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Root part. |
| `data-sync-key` | prop | - | Reflects the sync key prop on the Root part. |
| `data-value` | state | - | Reflects the value state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `TabsValue` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Tabs value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `TabsValue` | TabsValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Tabs. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false, sync: true | Yes | Updates the current Tabs value from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| tabs | provides | orientation, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-tabs`, `data-default-value`, `data-orientation`, `data-sync-key`, `data-value` | The tabs root needs initial value, orientation, and optional sync key before controller hydration. |

### List
The list of selectable Tabs items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-tabs-list` |
| Role | `tablist` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| activateOnFocus | `boolean` | false | option | Configures the activate on focus option for the List part. | - |
| loopFocus | `boolean` | true | option | Lets keyboard focus wrap around the Tabs items. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tabs-list` | runtime | - | Marks the List part so Starwind Runtime can find it. |
| `data-activate-on-focus` | prop | - | Reflects the activate on focus prop on the List part. |
| `data-loop-focus` | prop | - | Reflects the loop focus prop on the List part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the List part. |
#### Refs
| Part | Public |
| --- | --- |
| list | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-tabs-list`, `data-activate-on-focus`, `data-loop-focus` | The tab list needs focus policy markers before the runtime refreshes orientation, linked tabs, and roles. |

### Tab
A selectable tab inside Tabs.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-tabs-tab` |
| Role | `tab` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Tab part. | - |
| value | `string` | - | option | Controls the current Tabs value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tabs-tab` | runtime | - | Marks the Tab part so Starwind Runtime can find it. |
| `data-active` | state | - | Reflects the active state on the Tab part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Tab part. |
| `data-orientation` | state | - | Reflects the orientation state on the Tab part. |
| `data-state` | state | - | Reflects the current state on the Tab part. |
| `data-value` | prop | - | Reflects the value prop on the Tab part. |
#### Refs
| Part | Public |
| --- | --- |
| tab | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-tabs-tab`, `data-disabled`, `data-value`, `type` | Tabs need value identity and button semantics before the controller wires ARIA, roving focus, state, and panel ids. |

### Panel
The content panel controlled by Tabs.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-tabs-panel` |
| Role | `tabpanel` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| keepMounted | `boolean` | false | rendering | Keeps the Panel part in the DOM when hidden. | - |
| value | `string` | - | option | Controls the current Tabs value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tabs-panel` | runtime | - | Marks the Panel part so Starwind Runtime can find it. |
| `data-active` | state | - | Reflects the active state on the Panel part. |
| `data-keep-mounted` | prop | - | Reflects the keep mounted prop on the Panel part. |
| `data-orientation` | state | - | Reflects the orientation state on the Panel part. |
| `data-state` | state | - | Reflects the current state on the Panel part. |
| `data-value` | prop | - | Reflects the value prop on the Panel part. |
#### Refs
| Part | Public |
| --- | --- |
| panel | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-tabs-panel`, `data-keep-mounted`, `data-value` | Panels start from stable value and keep-mounted markers; the runtime links ids and active visibility during refresh. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | keepMounted |

### Indicator
Visual state indicator rendered by Tabs.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-tabs-indicator` |
| Role | `presentation` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tabs-indicator` | runtime | - | Marks the Indicator part so Starwind Runtime can find it. |
| `data-orientation` | state | - | Reflects the orientation state on the Indicator part. |
#### Refs
| Part | Public |
| --- | --- |
| indicator | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-tabs-indicator` | The indicator receives presentation semantics, visibility, and measured CSS variables from the runtime once an active tab is available. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createTabs`](/docs/runtime/#create-tabs) |
| Import | `@starwind-ui/runtime/tabs` |
| Root part | root |
| Option props | defaultValue, orientation, syncKey, value |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Tabs](/docs/components/tabs/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/tabs` | `createTabs` |
| Astro Primitive | `@starwind-ui/astro/tabs` | `Tabs`, `TabsRoot`, `TabsList`, `TabsTab`, `TabsPanel`, `TabsIndicator` |
| React Primitive | `@starwind-ui/react/tabs` | `Tabs`, `TabsRoot`, `TabsList`, `TabsTab`, `TabsPanel`, `TabsIndicator` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Tabs` |
| runtime-factory | `createTabs` |
| part | `Tabs.Root` |
| part | `Tabs.List` |
| part | `Tabs.Tab` |
| part | `Tabs.Panel` |
| part | `Tabs.Indicator` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced tab selection, roving focus, panel presence, orientation, and synchronized groups.

---

Source: [https://starwind.dev/docs/primitives/toast/](https://starwind.dev/docs/primitives/toast/) · [Markdown](https://starwind.dev/docs/primitives/toast.md)

# Toast Primitive

Toast is a Starwind Runtime primitive in the notification-system contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Toast anatomy with the Runtime wiring included.
```astro
---
import { Toast } from "@starwind-ui/astro/toast";
---

<Toast.Viewport>
  <Toast.Root>
    <Toast.Content>
      <Toast.Title>Saved</Toast.Title>
      <Toast.Description>Your changes were saved.</Toast.Description>
    </Toast.Content>
    <Toast.Close>Dismiss</Toast.Close>
  </Toast.Root>
</Toast.Viewport>
```

### React
Use the React primitive adapter when Toast state participates in React rendering.
```tsx
import { Toast } from "@starwind-ui/react/toast";

export function Example() {
  return (
    <Toast.Viewport>
      <Toast.Root>
        <Toast.Content>
          <Toast.Title>Saved</Toast.Title>
          <Toast.Description>Your changes were saved.</Toast.Description>
        </Toast.Content>
        <Toast.Close>Dismiss</Toast.Close>
      </Toast.Root>
    </Toast.Viewport>
  );
}
```

### HTML
Render the Toast data-sw-* contract yourself, then initialize createToastManager.
```html
<div data-sw-toast-viewport role="region" aria-live="polite" aria-atomic="false" aria-relevant="additions text" aria-label="Notifications" tabindex="-1">
  <div data-sw-toast-root>
    <div data-sw-toast-content>
      <div data-sw-toast-title>Saved</div>
      <div data-sw-toast-description>Your changes were saved.</div>
    </div>
    <button data-sw-toast-close type="button" aria-label="Close notification">Dismiss</button>
  </div>
</div>

const root = document.querySelector("[data-sw-toast-viewport]");
  if (root) {
    createToastManager(root);
  }
</script>
```
## API Reference
### Viewport
The visible viewport for Toast content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toast-viewport` |
| Role | `region` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| duration | `number` | 5000 | option | Configures the duration option for the Viewport part. | - |
| gap | `string` | "0.5rem" | option | Configures the gap option for the Viewport part. | - |
| limit | `number` | 3 | option | Configures the limit option for the Viewport part. | - |
| peek | `string` | "1rem" | option | Configures the peek option for the Viewport part. | - |
| position | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | "bottom-right" | option | Configures the position option for the Viewport part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
| `data-position` | prop | - | Reflects the position prop on the Viewport part. |
| `data-limit` | prop | - | Reflects the limit prop on the Viewport part. |
| `data-duration` | prop | - | Reflects the duration prop on the Viewport part. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `role`, `data-position`, `data-limit`, `data-duration`, `aria-live`, `aria-atomic`, `aria-relevant`, `aria-label`, `tabIndex` | The live region and manager configuration must be present before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Template
Template markup used to create Toast items.
| Fact | Value |
| --- | --- |
| Default element | `template` |
| Discovery hook | `data-sw-toast-template` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| variant | `"default" \| "error" \| "info" \| "loading" \| "success" \| "warning"` | "default" | option | Selects the visual variant for the Template part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-template` | runtime | - | Marks the Template part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| template | Yes |

### Root
The main element that owns the Toast Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toast-root` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| variant | `"default" \| "error" \| "info" \| "loading" \| "success" \| "warning"` | "default" | option | Selects the visual variant for the Root part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-root` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-toast-id` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Root part. |
| `data-variant` | prop | - | Reflects the variant prop on the Root part. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-state`, `data-variant` | Toast templates are cloned by the runtime and need the starting visual state. |

### Content
The content container rendered by Toast.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toast-content` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-content` | runtime | - | Marks the Content part so Starwind Runtime can find it. |

### Title
The accessible title for Toast.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toast-title` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-title` | runtime | - | Marks the Title part so Starwind Runtime can find it. |

### Title Text
Text content for the Toast title.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-toast-title-text` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-title-text` | runtime | - | Marks the Title Text part so Starwind Runtime can find it. |

### Description
Supporting description text for Toast.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toast-description` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-description` | runtime | - | Marks the Description part so Starwind Runtime can find it. |

### Action
An optional action button shown inside Toast.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-toast-action` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-action` | runtime | - | Marks the Action part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| action | Yes |

### Close
A control that closes Toast.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-toast-close` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-close` | runtime | - | Marks the Close part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| close | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `type`, `aria-label` | Generated close controls need an accessible label in the cloned template. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createToastManager`](/docs/runtime/#create-toast-manager) |
| Import | `@starwind-ui/runtime/toast` |
| Root part | viewport |
| Option props | - |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Toast](/docs/components/toast/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/toast` | `createToastManager` |
| Astro Primitive | `@starwind-ui/astro/toast` | `Toast`, `ToastViewport`, `ToastTemplate`, `ToastRoot`, `ToastContent`, `ToastTitle`, `ToastTitleText`, `ToastDescription`, `ToastAction`, `ToastClose` |
| React Primitive | `@starwind-ui/react/toast` | `Toast`, `ToastViewport`, `ToastTemplate`, `ToastRoot`, `ToastContent`, `ToastTitle`, `ToastTitleText`, `ToastDescription`, `ToastAction`, `ToastClose` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Toast` |
| runtime-factory | `createToastManager` |
| part | `Toast.Viewport` |
| part | `Toast.Template` |
| part | `Toast.Root` |
| part | `Toast.Content` |
| part | `Toast.Title` |
| part | `Toast.TitleText` |
| part | `Toast.Description` |
| part | `Toast.Action` |
| part | `Toast.Close` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced the toast manager, templates, updates, dismissal, pause behavior, and notification lifecycle.

---

Source: [https://starwind.dev/docs/primitives/toggle/](https://starwind.dev/docs/primitives/toggle/) · [Markdown](https://starwind.dev/docs/primitives/toggle.md)

# Toggle Primitive

Toggle is a Starwind Runtime primitive in the single-boolean-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Toggle anatomy with the Runtime wiring included.
```astro
---
import { Toggle } from "@starwind-ui/astro/toggle";
---

<Toggle.Root>Toggle</Toggle.Root>
```

### React
Use the React primitive adapter when Toggle state participates in React rendering.
```tsx
import { Toggle } from "@starwind-ui/react/toggle";

export function Example() {
  return (
    <Toggle.Root>Toggle</Toggle.Root>
  );
}
```

### HTML
Render the Toggle data-sw-* contract yourself, then initialize createToggle.
```html
<button data-sw-toggle>Toggle</button>

const root = document.querySelector("[data-sw-toggle]");
  if (root) {
    createToggle(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Toggle Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-toggle` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| pressed | `boolean` | - | control | Controls the pressed state for Toggle. | **React:** Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.<br>**Astro:** Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.<br>**Runtime / HTML:** Use data-default-pressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates. |
| defaultPressed | `boolean` | false | control | Controls the default pressed state for Toggle. | **React:** Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.<br>**Astro:** Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.<br>**Runtime / HTML:** Use data-default-pressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| nativeButton | `boolean` | true | rendering | Renders the control as a native button element. | - |
| syncGroup | `string` | - | option | Configures the sync group option for the Root part. | - |
| value | `string` | - | option | Controls the current Toggle value. | - |
| onPressedChange | `(pressed: boolean, details: TogglePressedChangeDetails) => void` | - | callback | Runs when on pressed change changes for Toggle. | **React:** Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.<br>**Astro:** Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.<br>**Runtime / HTML:** Use data-default-pressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toggle` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-pressed` | prop | - | Reflects the default pressed prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-native` | prop | - | Reflects the native prop on the Root part. |
| `data-pressed` | state | - | Reflects the pressed state on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
| `data-sync-group` | prop | - | Reflects the sync group prop on the Root part. |
| `data-unpressed` | state | - | Reflects the unpressed state on the Root part. |
| `data-value` | prop | - | Reflects the value prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| pressed | `boolean` | pressed | defaultPressed | `data-default-pressed` | `getPressed` | `setPressed` | Tracks whether Toggle is pressed. | **React:** Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.<br>**Astro:** Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.<br>**Runtime / HTML:** Use data-default-pressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| pressedChange | onPressedChange | starwind:pressed-change | pressed: `boolean` | TogglePressedChangeDetails | before-state-commit | Yes | Fires when the pressed state changes for Toggle. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setPressed` | state: pressed | emit: false, sync: true | Yes | Updates whether Toggle is pressed from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Toggle is disabled from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| toggle-group | consumes | disabled, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-toggle`, `aria-pressed`, `data-default-pressed`, `data-state`, `data-value` | Toggle state styling and ARIA button state must be correct before hydration. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createToggle`](/docs/runtime/#create-toggle) |
| Import | `@starwind-ui/runtime/toggle` |
| Root part | root |
| Option props | defaultPressed, disabled, nativeButton, pressed, syncGroup, value |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Toggle](/docs/components/toggle/) | Direct Primitive |
| [Toggle Group](/docs/components/toggle-group/) | Composite |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/toggle` | `createToggle` |
| Astro Primitive | `@starwind-ui/astro/toggle` | `Toggle`, `ToggleRoot` |
| React Primitive | `@starwind-ui/react/toggle` | `Toggle`, `ToggleRoot` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Toggle` |
| runtime-factory | `createToggle` |
| part | `Toggle.Root` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.1
- Prevented generic Toggle initialization from claiming roots owned by the Runtime Theme Toggle.
### v0.1.0
- Introduced pressed state, disabled behavior, and pressed-change events.

---

Source: [https://starwind.dev/docs/primitives/toggle-group/](https://starwind.dev/docs/primitives/toggle-group/) · [Markdown](https://starwind.dev/docs/primitives/toggle-group.md)

# Toggle Group Primitive

Toggle Group is a Starwind Runtime primitive in the controlled-value-group contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render ToggleGroup anatomy with the Runtime wiring included.
```astro
---
import { ToggleGroup } from "@starwind-ui/astro/toggle-group";
---

<ToggleGroup.Root />
```

### React
Use the React primitive adapter when ToggleGroup state participates in React rendering.
```tsx
import { ToggleGroup } from "@starwind-ui/react/toggle-group";

export function Example() {
  return (
    <ToggleGroup.Root />
  );
}
```

### HTML
Render the ToggleGroup data-sw-* contract yourself, then initialize createToggleGroup.
```html
<div data-sw-toggle-group role="group"></div>

const root = document.querySelector("[data-sw-toggle-group]");
  if (root) {
    createToggleGroup(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Toggle Group Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toggle-group` |
| Role | `group` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `ToggleGroupValue` | - | control | Controls the current Toggle Group value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `ToggleGroupValue` | - | control | Sets the initial Toggle Group value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| loopFocus | `boolean` | true | option | Lets keyboard focus wrap around the Toggle Group items. | - |
| multiple | `boolean` | false | option | Allows multiple Toggle Group values to be selected. | - |
| orientation | `"horizontal" \| "vertical"` | "horizontal" | option | Sets the Toggle Group orientation. | - |
| onValueChange | `(value: ToggleGroupValue, details: ToggleGroupValueChangeDetails) => void` | - | callback | Runs when the Toggle Group value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toggle-group` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-loop-focus` | prop | - | Reflects the loop focus prop on the Root part. |
| `data-multiple` | prop | - | Reflects the multiple prop on the Root part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Root part. |
| `data-value` | state | - | Reflects the value state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `ToggleGroupValue` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Toggle Group value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `ToggleGroupValue` | ToggleGroupValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Toggle Group. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Toggle Group value from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Toggle Group is disabled from Runtime code. |
| `setLoopFocus` | prop: loopFocus | - | No | Updates Toggle Group keyboard focus wrapping from Runtime code. |
| `setMultiple` | prop: multiple | - | No | Updates whether Toggle Group allows multiple values from Runtime code. |
| `setOrientation` | prop: orientation | - | No | Updates the Toggle Group orientation from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| toggle-group | provides | disabled, loopFocus, multiple, orientation, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-toggle-group`, `role`, `data-default-value`, `data-disabled`, `data-loop-focus`, `data-multiple`, `data-orientation`, `data-value` | The value group needs initial selection, orientation, and group state for styling before hydration. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createToggleGroup`](/docs/runtime/#create-toggle-group) |
| Import | `@starwind-ui/runtime/toggle-group` |
| Root part | root |
| Option props | defaultValue, disabled, loopFocus, multiple, orientation, value |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Toggle Group](/docs/components/toggle-group/) | Composite |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/toggle-group` | `createToggleGroup` |
| Astro Primitive | `@starwind-ui/astro/toggle-group` | `ToggleGroup`, `ToggleGroupRoot` |
| React Primitive | `@starwind-ui/react/toggle-group` | `ToggleGroup`, `ToggleGroupRoot` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `ToggleGroup` |
| runtime-factory | `createToggleGroup` |
| part | `ToggleGroup.Root` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.1
- Included the generated React context provider in vendored Toggle Group output so items receive current group state.
### v0.1.0
- Introduced single and multiple grouped toggle state with coordinated keyboard navigation.

---

Source: [https://starwind.dev/docs/primitives/tooltip/](https://starwind.dev/docs/primitives/tooltip/) · [Markdown](https://starwind.dev/docs/primitives/tooltip.md)

# Tooltip Primitive

Tooltip is a Starwind Runtime primitive in the presence-floating-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Tooltip anatomy with the Runtime wiring included.
```astro
---
import { Tooltip } from "@starwind-ui/astro/tooltip";
---

<Tooltip.Root>
  <Tooltip.Trigger>Hover me</Tooltip.Trigger>
  <Tooltip.Positioner>
    <Tooltip.Popup>
      <Tooltip.Arrow />
    </Tooltip.Popup>
  </Tooltip.Positioner>
</Tooltip.Root>
```

### React
Use the React primitive adapter when Tooltip state participates in React rendering.
```tsx
import { Tooltip } from "@starwind-ui/react/tooltip";

export function Example() {
  return (
    <Tooltip.Root>
      <Tooltip.Trigger>Hover me</Tooltip.Trigger>
      <Tooltip.Positioner>
        <Tooltip.Popup>
          <Tooltip.Arrow />
        </Tooltip.Popup>
      </Tooltip.Positioner>
    </Tooltip.Root>
  );
}
```

### HTML
Render the Tooltip data-sw-* contract yourself, then initialize createTooltip.
```html
<div data-sw-tooltip>
  <button data-sw-tooltip-trigger type="button">Hover me</button>
  <div data-sw-tooltip-positioner>
    <div data-sw-tooltip-popup role="tooltip" hidden>
      <div data-sw-tooltip-arrow></div>
    </div>
  </div>
</div>

const root = document.querySelector("[data-sw-tooltip]");
  if (root) {
    createTooltip(root);
  }
</script>
```
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | trigger |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, avoidCollisions |
## API Reference
### Root
The main element that owns the Tooltip Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-tooltip` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Tooltip is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Tooltip starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| closeDelay | `number` | 200 | option | Sets how long Tooltip waits before closing. | - |
| closeOnEscape | `boolean` | true | option | Closes Tooltip when Escape is pressed. | - |
| closeOnOutsideInteract | `boolean` | true | option | Closes Tooltip when the user interacts outside it. | - |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| disableHoverableContent | `boolean` | false | option | Configures the disable hoverable content option for the Root part. | - |
| openDelay | `number` | 200 | option | Sets how long Tooltip waits before opening. | - |
| onOpenChange | `(open: boolean, details: TooltipOpenChangeDetails) => void` | - | callback | Runs when Tooltip opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tooltip` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Root part. |
| `data-close-on-escape` | prop | - | Reflects the close on escape prop on the Root part. |
| `data-close-on-outside-interact` | prop | - | Reflects the close on outside interact prop on the Root part. |
| `data-content-hoverable` | prop | - | Reflects the content hoverable prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-open-delay` | prop | - | Reflects the open delay prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Tooltip is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | TooltipOpenChangeDetails | before-state-commit | Yes | Fires when Tooltip opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Tooltip from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Tooltip is disabled from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-tooltip`, `data-default-open`, `data-close-delay`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-content-hoverable`, `data-disabled`, `data-open-delay`, `data-state` | The tooltip root needs timing, dismissal, disabled, hoverability, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Tooltip content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-tooltip-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tooltip-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-as-child` | prop | - | Reflects the as child prop on the Trigger part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | data, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-tooltip-trigger`, `data-as-child`, `data-disabled`, `aria-disabled`, `data-state`, `disabled`, `type` | Triggers need disabled state and initial closed state before pointer/focus listeners attach. |

### Portal
Moves Tooltip overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-tooltip-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tooltip-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Positioner
Positions the Tooltip content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-tooltip-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "top" | option | Sets the preferred side for Tooltip content. | - |
| align | `"start" \| "center" \| "end"` | "center" | option | Sets how Tooltip content aligns to its trigger. | - |
| sideOffset | `number` | 8 | option | Sets the distance between Tooltip content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Tooltip content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tooltip-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Positioner part. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |
#### Refs
| Part | Public |
| --- | --- |
| positioner | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-tooltip-positioner`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions` | The positioner carries initial placement hints used by the shared floating runtime. |

### Popup
The floating content container for Tooltip.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-tooltip-popup` |
| Role | `tooltip` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "top" | option | Sets the preferred side for Tooltip content. | - |
| align | `"start" \| "center" \| "end"` | "center" | option | Sets how Tooltip content aligns to its trigger. | - |
| sideOffset | `number` | 8 | option | Sets the distance between Tooltip content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Tooltip content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tooltip-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-tooltip-popup`, `role`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions`, `hidden` | The tooltip popup starts hidden with tooltip semantics and initial placement hints before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Arrow
The arrow element that visually points to the trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-tooltip-arrow` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-tooltip-arrow` | runtime | - | Marks the Arrow part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Arrow part. |
#### Refs
| Part | Public |
| --- | --- |
| arrow | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-tooltip-arrow`, `data-state` | The arrow receives state and placement updates from the floating runtime. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createTooltip`](/docs/runtime/#create-tooltip) |
| Import | `@starwind-ui/runtime/tooltip` |
| Root part | root |
| Option props | closeDelay, closeOnEscape, closeOnOutsideInteract, defaultOpen, disabled, disableHoverableContent, onOpenChange, open, openDelay |
| Option lifecycles | closeDelay: constructor-only, closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultOpen: constructor-only, disabled: setter-backed, disableHoverableContent: constructor-only, onOpenChange: constructor-only, open: setter-backed, openDelay: constructor-only |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Tooltip](/docs/components/tooltip/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/tooltip` | `createTooltip` |
| Astro Primitive | `@starwind-ui/astro/tooltip` | `Tooltip`, `TooltipRoot`, `TooltipTrigger`, `TooltipPortal`, `TooltipPositioner`, `TooltipPopup`, `TooltipArrow` |
| React Primitive | `@starwind-ui/react/tooltip` | `Tooltip`, `TooltipRoot`, `TooltipTrigger`, `TooltipPortal`, `TooltipPositioner`, `TooltipPopup`, `TooltipArrow` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Tooltip` |
| runtime-factory | `createTooltip` |
| part | `Tooltip.Root` |
| part | `Tooltip.Trigger` |
| part | `Tooltip.Portal` |
| part | `Tooltip.Positioner` |
| part | `Tooltip.Popup` |
| part | `Tooltip.Arrow` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced hover and focus timing, floating placement, presence, and dismissal for accessible tooltips.

---

Source: [https://starwind.dev/docs/runtime/](https://starwind.dev/docs/runtime/) · [Markdown](https://starwind.dev/docs/runtime.md)

# Runtime And Raw HTML

{/* Generated by scripts/portable-runtime/generate-layered-docs-metadata.ts. Do not edit directly. */}

The Runtime surface is for raw HTML and framework adapters that already render the Starwind DOM
contract. It owns initialization, cleanup, discovery hooks, factories, DOM events, instance
methods, and theme helpers without requiring Astro or React.

Use styled components first when you want ready-to-render UI. Use the Runtime directly when you are
rendering static markup, building a framework adapter, or integrating Starwind behavior into a
non-framework surface.

## Init Starwind

`initStarwind` scans a root node for Starwind discovery attributes and initializes each matching
primitive in cleanup order. Store the returned cleanup object and call `destroy()` when that root
leaves the page.

```ts
import { initStarwind } from "@starwind-ui/runtime/init-starwind";

const starwind = initStarwind(document);

// Later, when the root is removed.
starwind.destroy();
```

## Raw HTML

Raw HTML uses `data-sw-*` discovery hooks for Runtime ownership. You provide the DOM contract, then
call `initStarwind(root?)` for automatic discovery or call a `create*` factory for one primitive
instance.

```html
<div data-sw-drawer>
  <button data-sw-drawer-trigger>Open</button>
  <div data-sw-drawer-popup hidden>
    <button data-sw-drawer-close>Close</button>
  </div>
</div>
```

The initializer registry below shows which selectors are discovered by `initStarwind`, which
factory owns each selector, and the cleanup order used when a root is destroyed.

## Data Attributes

Runtime discovery attributes use the `data-sw-*` prefix. Primitive state, options, and measured
values use short scoped `data-*` attributes such as `data-state`, `data-value`, `data-side`, and
`data-auto-init`.

Treat `data-sw-*` attributes as behavior hooks. Treat `data-slot` as public part identity for
styling and documentation. Styled components may add classes, variants, and slots around the same
Runtime-owned behavior contract.

## Runtime Factories

Every primitive has a `create*` factory. Framework adapters call these factories after rendering
primitive anatomy; raw HTML can call them directly when you want explicit ownership instead of
document-wide discovery.

Factories expose option props, state models, DOM events, and setter methods. Setter calls update the
Runtime instance without requiring a framework render cycle.

## Lifecycle And Cleanup

`initStarwind` returns a cleanup object for the initialized root. Calling `destroy()` tears down
listeners, observers, timers, floating behavior, portals, and runtime-owned presence for primitives
created under that root.

Some raw HTML initializers are ordered because child primitives depend on parent providers or form
state. Use the cleanup order in the raw HTML table when you build a custom adapter or manual
initializer.

## Events And State

Runtime factories bridge controlled and uncontrolled state with DOM events. For example,
`createDrawer` exposes open state, emits `starwind:open-change`, and provides setter methods for
updating state from framework adapters or custom DOM code.

Use event names from the factory table when listening from raw HTML. Use callback props from the
framework adapter when you are inside Astro or React primitives.

## Theme

Theme helpers are part of the Runtime surface. Use `createThemeController` for interactive controls
and `getThemeInitScript` before paint to apply the initial color theme.

Theme controls are discovered through selectors such as `[data-sw-theme-control]` and
`[data-sw-theme-toggle]`. The Runtime emits `starwind:theme-change` when the active theme changes.

## Runtime Reference
Use the Runtime directly when raw HTML or a framework adapter already renders the Starwind DOM contract.
| Fact | Value |
| --- | --- |
| Package | `@starwind-ui/runtime` |
| Initializer | `initStarwind(root?: ParentNode): StarwindCleanup` |
| Import | `@starwind-ui/runtime/init-starwind` |
| Cleanup | Store the returned cleanup object and call `destroy()` when the initialized root leaves the page. |
## Raw HTML Initializers
Raw HTML uses `data-sw-*` discovery hooks for Runtime ownership.
| Selector | Factory | Primitive | Cleanup Order | Notes |
| --- | --- | --- | --- | --- |
| `[data-sw-button][data-focusable-when-disabled]` | [`createButton`](/docs/runtime/#create-button) | [button](/docs/primitives/button/) | 0 | - |
| `[data-sw-form]` | [`createForm`](/docs/runtime/#create-form) | [form](/docs/primitives/form/) | 1 | - |
| `[data-sw-field]` | [`createField`](/docs/runtime/#create-field) | [field](/docs/primitives/field/) | 2 | - |
| `[data-sw-fieldset]` | [`createFieldset`](/docs/runtime/#create-fieldset) | [fieldset](/docs/primitives/fieldset/) | 2 | - |
| `[data-sw-input]` | [`createInput`](/docs/runtime/#create-input) | [input](/docs/primitives/input/) | 3 | - |
| `[data-sw-input-otp]` | [`createInputOtp`](/docs/runtime/#create-input-otp) | [input-otp](/docs/primitives/input-otp/) | 4 | - |
| `[data-sw-color-picker]` | [`createColorPicker`](/docs/runtime/#create-color-picker) | [color-picker](/docs/primitives/color-picker/) | 5 | - |
| `[data-sw-slider]` | [`createSlider`](/docs/runtime/#create-slider) | [slider](/docs/primitives/slider/) | 5 | - |
| `[data-sw-switch]` | [`createSwitch`](/docs/runtime/#create-switch) | [switch](/docs/primitives/switch/) | 6 | - |
| `[data-sw-tabs]` | [`createTabs`](/docs/runtime/#create-tabs) | [tabs](/docs/primitives/tabs/) | 6 | - |
| `[data-sw-toggle-group]` | [`createToggleGroup`](/docs/runtime/#create-toggle-group) | [toggle-group](/docs/primitives/toggle-group/) | 7 | - |
| `[data-sw-toggle]` | [`createToggle`](/docs/runtime/#create-toggle) | [toggle](/docs/primitives/toggle/) | 8 | - |
| `[data-sw-avatar]` | [`createAvatar`](/docs/runtime/#create-avatar) | [avatar](/docs/primitives/avatar/) | 9 | - |
| `[data-sw-checkbox-group]` | [`createCheckboxGroup`](/docs/runtime/#create-checkbox-group) | [checkbox-group](/docs/primitives/checkbox-group/) | 10 | - |
| `[data-sw-checkbox]` | [`createCheckbox`](/docs/runtime/#create-checkbox) | [checkbox](/docs/primitives/checkbox/) | 11 | - |
| `[data-sw-radio-group]` | [`createRadioGroup`](/docs/runtime/#create-radio-group) | [radio-group](/docs/primitives/radio-group/) | 12 | - |
| `[data-sw-radio]` | [`createRadio`](/docs/runtime/#create-radio) | [radio](/docs/primitives/radio/) | 13 | - |
| `[data-sw-scroll-area]` | [`createScrollArea`](/docs/runtime/#create-scroll-area) | [scroll-area](/docs/primitives/scroll-area/) | 14 | - |
| `[data-sw-select]` | [`createSelect`](/docs/runtime/#create-select) | [select](/docs/primitives/select/) | 15 | - |
| `[data-sw-sidebar-provider]` | [`createSidebarController`](/docs/runtime/#create-sidebar-controller) | [sidebar](/docs/primitives/sidebar/) | 16 | Initialized once per initStarwind root. |
| `[data-sw-combobox]` | [`createCombobox`](/docs/runtime/#create-combobox) | [combobox](/docs/primitives/combobox/) | 17 | - |
| `[data-sw-accordion]` | [`createAccordion`](/docs/runtime/#create-accordion) | [accordion](/docs/primitives/accordion/) | 18 | - |
| `[data-sw-collapsible]` | [`createCollapsible`](/docs/runtime/#create-collapsible) | [collapsible](/docs/primitives/collapsible/) | 19 | - |
| `[data-sw-dialog]` | [`createDialog`](/docs/runtime/#create-dialog) | [dialog](/docs/primitives/dialog/) | 20 | - |
| `[data-sw-alert-dialog]` | [`createAlertDialog`](/docs/runtime/#create-alert-dialog) | [alert-dialog](/docs/primitives/alert-dialog/) | 21 | - |
| `[data-sw-drawer]` | [`createDrawer`](/docs/runtime/#create-drawer) | [drawer](/docs/primitives/drawer/) | 22 | - |
| `[data-sw-dropzone]` | [`createDropzone`](/docs/runtime/#create-dropzone) | [dropzone](/docs/primitives/dropzone/) | 23 | - |
| `[data-sw-carousel]` | [`createCarousel`](/docs/runtime/#create-carousel) | [carousel](/docs/primitives/carousel/) | 24 | Skips elements with data-auto-init="false". |
| `[data-sw-context-menu]` | [`createContextMenu`](/docs/runtime/#create-context-menu) | [context-menu](/docs/primitives/context-menu/) | 25 | - |
| `[data-sw-menu]` | [`createMenu`](/docs/runtime/#create-menu) | [menu](/docs/primitives/menu/) | 26 | Skips menu roots that are also context-menu roots. |
| `[data-sw-nav-menu]` | [`createNavigationMenu`](/docs/runtime/#create-navigation-menu) | [navigation-menu](/docs/primitives/navigation-menu/) | 27 | - |
| `[data-sw-popover]` | [`createPopover`](/docs/runtime/#create-popover) | [popover](/docs/primitives/popover/) | 27 | - |
| `[data-sw-preview-card]` | [`createPreviewCard`](/docs/runtime/#create-preview-card) | [preview-card](/docs/primitives/preview-card/) | 28 | - |
| `[data-sw-progress]` | [`createProgress`](/docs/runtime/#create-progress) | [progress](/docs/primitives/progress/) | 29 | - |
| `[data-sw-tooltip]` | [`createTooltip`](/docs/runtime/#create-tooltip) | [tooltip](/docs/primitives/tooltip/) | 30 | - |
| `[data-sw-toast-viewport]` | [`createToastManager`](/docs/runtime/#create-toast-manager) | [toast](/docs/primitives/toast/) | 31 | - |
| `[data-sw-theme-control], [data-sw-theme-toggle]` | [`initThemeController`](/docs/runtime/) | - | 32 | Initialized once per initStarwind root. |
## Data Attribute Conventions
| Prefix | Purpose | Examples |
| --- | --- | --- |
| `data-sw-*` | Runtime discovery hooks. | `data-sw-drawer`, `data-sw-menu`, `data-sw-theme-toggle` |
| `data-*` | Scoped state and option attributes owned by a primitive. | `data-state`, `data-value`, `data-side`, `data-auto-init` |
## Adapter Responsibilities
| Surface | Import | Responsibility |
| --- | --- | --- |
| Raw HTML | `@starwind-ui/runtime/init-starwind` | You write the DOM contract and call initStarwind(root?) or a create* factory. |
| Astro Primitive adapters | `@starwind-ui/astro` | Adapters render primitive anatomy and attributes while the Runtime owns DOM behavior. |
| React Primitive adapters | `@starwind-ui/react` | Adapters expose framework props and refs for the same Runtime primitive contract. |
## Runtime Factories
| Factory | Import | Options | State | Events | Setters |
| --- | --- | --- | --- | --- | --- |
| `createAccordion` | `@starwind-ui/runtime/accordion` | type, defaultValue, collapsible, value | value | valueChange (starwind:value-change) | `setValue` -> state: value |
| `createAlertDialog` | `@starwind-ui/runtime/alert-dialog` | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open | open | closeComplete (starwind:close-complete), openChange (starwind:open-change) | `setOpen` -> state: open |
| `createAvatar` | `@starwind-ui/runtime/avatar` | - | imageLoadingStatus | loadingStatusChange (starwind:loading-status-change) | - |
| `createButton` | `@starwind-ui/runtime/button` | disabled | - | - | `setDisabled` -> prop: disabled |
| `createCarousel` | `@starwind-ui/runtime/carousel` | orientation, opts, plugins, setApi | - | - | - |
| `createCheckbox` | `@starwind-ui/runtime/checkbox` | checked, defaultChecked, disabled, form, id, indeterminate, name, readOnly, required, uncheckedValue, value | checked, indeterminate | checkedChange (starwind:checked-change) | `setChecked` -> state: checked, `setIndeterminate` -> state: indeterminate, `setDisabled` -> prop: disabled |
| `createCheckboxGroup` | `@starwind-ui/runtime/checkbox-group` | defaultValue, disabled, value | value | valueChange (starwind:value-change) | `setValue` -> state: value, `setDisabled` -> prop: disabled |
| `createCollapsible` | `@starwind-ui/runtime/collapsible` | defaultOpen, disabled, open | open | openChange (starwind:open-change) | `setOpen` -> state: open |
| `createColorPicker` | `@starwind-ui/runtime/color-picker` | value, defaultValue, format, alpha, allowEmpty, disabled, readOnly, name, form, required, locale, dir, getAriaValueText, getAreaRoleDescription, getColorDescription, onValueChange, onValueCommitted, onFormatChange | value, format | valueChange (starwind:value-change), valueCommitted (starwind:value-committed), formatChange (starwind:format-change) | `setValue` -> state: value, `setFormat` -> state: format, `setDisabled` -> prop: disabled, `setReadOnly` -> prop: readOnly, `setName` -> prop: name, `setOptions` -> props: alpha, allowEmpty, dir, form, getAreaRoleDescription, getAriaValueText, getColorDescription, locale, required |
| `createCombobox` | `@starwind-ui/runtime/combobox` | autoComplete, defaultInputValue, defaultOpen, defaultValue, disabled, filterMode, form, highlightItemOnHover, inputValue, locale, modal, name, open, readOnly, required, value | inputValue, open, value | inputValueChange (starwind:input-value-change), openChange (starwind:open-change), valueChange (starwind:value-change) | `setDisabled` -> prop: disabled, `setInputValue` -> state: inputValue, `setOpen` -> state: open, `setValue` -> state: value |
| `createContextMenu` | `@starwind-ui/runtime/context-menu` | closeDelay, defaultOpen, disabled, modal, onCloseComplete, onOpenChange, open | open, checked, radioValue | openChange (starwind:open-change), closeComplete (starwind:close-complete), checkedChange (starwind:checked-change), valueChange (starwind:value-change) | `setOpen` -> state: open |
| `createDialog` | `@starwind-ui/runtime/dialog` | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open | open | openChange (starwind:open-change), closeComplete (starwind:close-complete) | `setOpen` -> state: open |
| `createDrawer` | `@starwind-ui/runtime/drawer` | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open | open | openChange (starwind:open-change), closeComplete (starwind:close-complete) | `setOpen` -> state: open |
| `createDropzone` | `@starwind-ui/runtime/dropzone` | disabled, isUploading, onFilesChange | uploading | filesChange (starwind:files-change) | `setDisabled` -> prop: disabled, `setUploading` -> prop: isUploading |
| `createField` | `@starwind-ui/runtime/field` | dirty, disabled, invalid, name, touched | dirty, touched | - | `setDirty` -> prop: dirty, `setDisabled` -> prop: disabled, `setInvalid` -> prop: invalid, `setName` -> prop: name, `setTouched` -> prop: touched |
| `createFieldset` | `@starwind-ui/runtime/fieldset` | disabled | - | - | `setDisabled` -> prop: disabled |
| `createForm` | `@starwind-ui/runtime/form` | - | - | - | - |
| `createInput` | `@starwind-ui/runtime/input` | defaultValue, disabled, onValueChange, value | value | valueChange (starwind:value-change) | `setValue` -> state: value, `setDisabled` -> prop: disabled |
| `createInputOtp` | `@starwind-ui/runtime/input-otp` | defaultValue, disabled, form, id, maxLength, name, onValueChange, pattern, readOnly, required, value | value | valueChange (starwind:value-change) | `setValue` -> state: value, `setDisabled` -> prop: disabled, `setFormOptions` -> props: form, id, name, required |
| `createMenu` | `@starwind-ui/runtime/menu` | closeDelay, defaultOpen, disabled, modal, onCloseComplete, onOpenChange, open, openOnHover | open, checked, radioValue | openChange (starwind:open-change), closeComplete (starwind:close-complete), checkedChange (starwind:checked-change), valueChange (starwind:value-change) | `setOpen` -> state: open |
| `createNavigationMenu` | `@starwind-ui/runtime/navigation-menu` | closeDelay, closeOnEscape, closeOnOutsideInteract, defaultValue, onValueChange, openDelay, value | value | valueChange (starwind:value-change) | `setValue` -> state: value |
| `createPopover` | `@starwind-ui/runtime/popover` | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open, openOnHover | open | openChange (starwind:open-change), closeComplete (starwind:close-complete) | `setOpen` -> state: open |
| `createPreviewCard` | `@starwind-ui/runtime/preview-card` | closeDelay, closeOnEscape, closeOnOutsideInteract, defaultOpen, disableHoverableContent, onOpenChange, open, openDelay | open | openChange (starwind:open-change) | `setOpen` -> state: open |
| `createProgress` | `@starwind-ui/runtime/progress` | format, getAriaValueText, locale, max, min, value | value | - | `setFormatOptions` -> props: format, getAriaValueText, locale, `setValue` -> props: value, max, min |
| `createRadio` | `@starwind-ui/runtime/radio` | checked, defaultChecked, disabled, form, id, name, readOnly, required, value | checked | checkedChange (starwind:checked-change) | `setChecked` -> state: checked, `setDisabled` -> prop: disabled, `setReadOnly` -> prop: readOnly, `setFormOptions` -> props: form, name, required, value |
| `createRadioGroup` | `@starwind-ui/runtime/radio-group` | defaultValue, disabled, form, name, orientation, readOnly, required, value | value | valueChange (starwind:value-change) | `setValue` -> state: value, `setDisabled` -> prop: disabled, `setFormOptions` -> props: form, name, required, `setName` -> prop: name, `setOrientation` -> prop: orientation, `setReadOnly` -> prop: readOnly, `setRequired` -> prop: required |
| `createScrollArea` | `@starwind-ui/runtime/scroll-area` | overflowEdgeThreshold | - | - | - |
| `createSelect` | `@starwind-ui/runtime/select` | autoComplete, defaultOpen, defaultValue, disabled, form, highlightItemOnHover, modal, open, readOnly, value | open, value | openChange (starwind:open-change), valueChange (starwind:value-change) | `setOpen` -> state: open, `setValue` -> state: value |
| `createSidebarController` | `@starwind-ui/runtime/sidebar` | defaultMobileOpen, defaultOpen, keyboardShortcut, mobileOpen, mobileQuery, onMobileOpenChange, onOpenChange, open, persistOpen, persistenceKey, persistenceMaxAge, persistenceStorage | open, mobileOpen | openChange (starwind:sidebar-change), mobileOpenChange (starwind:sidebar-mobile-change) | `setOpen` -> state: open, `setMobileOpen` -> state: mobileOpen |
| `createSlider` | `@starwind-ui/runtime/slider` | defaultValue, disabled, form, largeStep, max, min, minStepsBetweenValues, name, orientation, step, value | value | valueChange (starwind:value-change), valueCommitted (starwind:value-committed) | `setValue` -> state: value, `setDisabled` -> prop: disabled, `setName` -> prop: name, `setOptions` -> props: form, largeStep, max, min, minStepsBetweenValues, orientation, step |
| `createSwitch` | `@starwind-ui/runtime/switch` | checked, defaultChecked, disabled, form, id, name, readOnly, required, uncheckedValue, value | checked | checkedChange (starwind:checked-change) | `setChecked` -> state: checked, `setDisabled` -> prop: disabled, `setFormOptions` -> props: form, name, required, uncheckedValue, value |
| `createTabs` | `@starwind-ui/runtime/tabs` | defaultValue, orientation, syncKey, value | value | valueChange (starwind:value-change) | `setValue` -> state: value |
| `createToastManager` | `@starwind-ui/runtime/toast` | - | - | - | - |
| `createToggle` | `@starwind-ui/runtime/toggle` | defaultPressed, disabled, nativeButton, pressed, syncGroup, value | pressed | pressedChange (starwind:pressed-change) | `setPressed` -> state: pressed, `setDisabled` -> prop: disabled |
| `createToggleGroup` | `@starwind-ui/runtime/toggle-group` | defaultValue, disabled, loopFocus, multiple, orientation, value | value | valueChange (starwind:value-change) | `setValue` -> state: value, `setDisabled` -> prop: disabled, `setLoopFocus` -> prop: loopFocus, `setMultiple` -> prop: multiple, `setOrientation` -> prop: orientation |
| `createTooltip` | `@starwind-ui/runtime/tooltip` | closeDelay, closeOnEscape, closeOnOutsideInteract, defaultOpen, disabled, disableHoverableContent, onOpenChange, open, openDelay | open | openChange (starwind:open-change) | `setOpen` -> state: open, `setDisabled` -> prop: disabled |
## Theme Helpers
| Helper | Import | Signature |
| --- | --- | --- |
| `createThemeController` | `@starwind-ui/runtime/theme` | `createThemeController(options?: ThemeControllerOptions): ThemeControllerInstance` |
| `initThemeController` | `@starwind-ui/runtime/theme` | `initThemeController(root?: ParentNode, options?: Omit<ThemeControllerOptions, "root">): ThemeControllerInstance` |
| `getThemeInitScript` | `@starwind-ui/runtime/theme` | `getThemeInitScript(options?: ThemeInitScriptOptions): string` |
## Theme Controls And Events
| Fact | Value |
| --- | --- |
| Control selectors | [data-sw-theme-control], [data-sw-theme-toggle] |
| Control attributes | data-theme-value, data-theme-on, data-theme-off, data-ready |
| Events | starwind:theme-change (StarwindThemeChangeDetails), theme:change (StarwindThemeChangeDetails) |

@starwind-ui starred 3 repositories

@starwind-ui starred 3 repositories

Small

Large

Independent popup size

Small

Large

Independent popup size

Theme accent

Theme accent