Button
A composable button primitive for actions, links, and custom elements.
Features
- Polymorphic rendering
- Native, link, or custom modes
- Semantic disabled behavior
- Button groups with position tracking
- Headless styling
Installation
npm install @ariaui/button
Examples
Each variant has its own live preview and snippet. Style Button.Root directly, or pass asChild and style the slotted link via className.
Primary
The default filled button for common actions.
No preview output yet.
Secondary
Use for less prominent actions.
No preview output yet.
Destructive
Use for actions that remove data or have high impact.
No preview output yet.
Outline
Use for neutral actions that still need a visible boundary.
No preview output yet.
Ghost
Use for lightweight actions that should stay visually quiet.
No preview output yet.
Link
Use when button styling should read like a text link.
No preview output yet.
With icon
Icons can sit to the left or right of the label.
No preview output yet.
Loading
Disabled state with a spinner while an action is in progress.
No preview output yet.
Sizes
Small, default, and large heights with matching padding.
No preview output yet.
Anatomy
import * as Button from "@ariaui/button";
export default function Example() {
return <Button.Root />;
}
API Reference
Root
Composable button primitive. Defaults to a native `<button>`. Pass `asChild` with a single child element for link or custom-element rendering.
| Prop | Type | Default |
|---|---|---|
asChild | boolean | false |
type | "button" | "submit" | "reset" | "button" |
disabled | boolean | false |
| Attribute | Values |
|---|---|
| [data-disabled] | Present when disabled |
Group
Structural container for related buttons. Provides context for descendant `Button.Item` registration. Renders a `<div>`.
| Prop | Type | Default |
|---|---|---|
role | string | "group" |
aria-label | string | — |
Item
Grouped button primitive for use inside `Button.Group`. Shares all composition and disabled behavior with `Root`. Automatically derives and reflects its position within the group via `data-position`.
| Prop | Type | Default |
|---|---|---|
asChild | boolean | false |
disabled | boolean | false |
| Attribute | Values |
|---|---|
| [data-position] | "only" | "first" | "middle" | "last" — derived automatically from group order |
| [data-disabled] | Present when disabled |
Keyboard
| Shortcut | Action |
|---|---|
| Tab | Move focus to the next focusable element. |
| Shift+Tab | Move focus to the previous focusable element. |
| Enter | Trigger the button's click event. |
| Space | Trigger the button's click event. For custom non-native elements, fires on keyup to avoid page scroll. |
Native <button> and <a> elements follow standard browser keyboard behavior. Custom non-native elements support manual Enter and Space activation.
Accessibility
The Button component renders semantic controls across three modes:
Native <button> elements use the standard disabled attribute. For navigation, pass asChild and render a real anchor or router link as the child; disabled anchors have their href removed and receive aria-disabled="true". Custom children receive role="button", tabIndex={0}, and manual keyboard activation for Enter and Space.
Button.Group and Button.Item are useful for grouping related actions. Items expose their position through data-position, which supports position-aware styling such as first and last item radius adjustments.