# Button Primitive

Button uses native button semantics by default and adds Runtime behavior only for focusable-disabled state.
## 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>
```
## 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 |
| --- | --- | --- | --- | --- |
| 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` |