# 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>

<script type="module">
  import { createButton } from "@starwind-ui/runtime/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>
```

### Vue
Use the Vue 3.5 beta adapter to render Button anatomy.
```vue
<script setup lang="ts">
import Button from "@starwind-ui/vue/button";
</script>

<template>
  <Button.Root type="button" :focusableWhenDisabled="true">Button</Button.Root>
</template>
```
## 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.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### 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.