@headless-ui/react-button

A headless, accessible React button component following the Radix UI patterns.

Features

• 🎨 Unstyled — bring your own styles with CSS, Tailwind, etc.
• ♿ Accessible — correct ARIA roles and keyboard behaviour out of the box
• 🔄 asChild support — render any element as a button using the Radix UI Slot pattern
• 🔁 Ref forwarding — access the underlying DOM element
• 📦 Dual ESM/CJS — works in any module system

Installation

pnpm add @headless-ui/react-button
# or
npm install @headless-ui/react-button
# or
yarn add @headless-ui/react-button

Usage

import { Button } from '@headless-ui/react-button';

// Basic usage
function App() {
  return <Button onClick={() => console.log('clicked')}>Click me</Button>;
}

With Tailwind CSS

<Button className="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700">
  Click me
</Button>

asChild — Polymorphic Rendering

Use the asChild prop to render a different element (e.g. a link) with all button props merged in:

import { Button } from '@headless-ui/react-button';

// Renders an <a> tag but receives the button's onClick and other props
<Button asChild>
  <a href="/dashboard">Go to Dashboard</a>
</Button>

This is especially useful for router link components:

import { Link } from 'react-router-dom';

<Button asChild>
  <Link to="/dashboard">Dashboard</Link>
</Button>

API

Button

| Prop | Type | Default | Description | |------|------|---------|-------------| | asChild | boolean | false | When true, renders the child element instead of <button>, merging all props. | | type | 'button' \| 'submit' \| 'reset' | 'button' | The button's type attribute. Defaults to 'button' to avoid accidental form submission. | | disabled | boolean | false | Disables the button. | | ref | React.Ref<HTMLButtonElement> | — | Forwarded ref to the underlying element. | | ...rest | React.ButtonHTMLAttributes<HTMLButtonElement> | — | All standard <button> HTML attributes are supported. |

License

MIT