On this page

Button Primitive

Button uses native button semantics by default and adds Runtime behavior only for focusable-disabled state.

Anatomy

Use the Astro primitive adapter to render Button anatomy with the Runtime wiring included.

---
import { Button } from "@starwind-ui/astro/button";
---

<Button.Root type="button" focusableWhenDisabled={true}>Button</Button.Root>

Use the React primitive adapter when Button state participates in React rendering.

import { Button } from "@starwind-ui/react/button";

export function Example() {
  return (
    <Button.Root type="button" focusableWhenDisabled={true}>Button</Button.Root>
  );
}

Render the Button data-sw-* contract yourself, then initialize createButton.

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

Default element: button
Discovery hook: data-sw-button
Role: -

Props

Prop Type Default

disabled boolean false

Description: Disables the button natively unless focusableWhenDisabled keeps it focusable through Runtime.
Kind: option
Targets: -
Full type: boolean

focusableWhenDisabled boolean false

Description: Opts the native button into Runtime so disabled state can suppress activation without removing focusability.
Kind: option
Targets: -
Full type: boolean

type button | submit | reset -

Description: Sets the native button type; adapters default an omitted value to button.
Kind: attribute
Targets: root
Full type: button | submit | reset

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-button - Runtime discovery hook for an opted-in native button.

Metadata

Attribute Value Description

data-focusable-when-disabled - Opts the native button into focusable-disabled Runtime behavior.

data-disabled - Present while an opted-in button is disabled through Runtime.

Runtime API

Factory: createButton
Import: @starwind-ui/runtime/button
Root hook: root data-sw-button
Option props: disabled

Option Lifecycles

Option	Lifecycle
disabled	setter-backed

Runtime Setters

Method Target Description

setDisabled prop: disabled Updates the opted-in button between enabled and focusable-disabled state without replacing it.

Component Relationship

Button Mixed conditional