On this page

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

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

Changelog

View version history v1.0.0 4 releases

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.