Button
A customizable button component with multiple variants and states.
- Supports keyboard activation with Enter and Space keys.
- Automatic aria-disabled handling when disabled.
- Polymorphic component rendering via Necto <Primitive />.
- Focus visible styles for keyboard navigation.
- Loading state with automatic disabled behavior.
Installation
Anatomy
Import from collection package and use Root component.
import { Button } from "@sprocketui/react";
export default () => (
<Button.Root>
Click Me
</Button.Root>
);You can also import pre-defined aliases for when there are namespace issues.
import { SprocketButton } from "@sprocketui/react";
export default () => (
<SprocketButton.Root>
Click Me
</SprocketButton.Root>
);States
{/* Loading state */}
<Button isPending>Loading...</Button>
{/* Disabled state */}
<Button isDisabled>Disabled</Button>API Reference
Root
Contains the content for the button.
Props
| Name | Type | Description |
|---|---|---|
isPending | boolean | Whether the button is in a pending state. This disables press and hover events while retaining focusability, and announces the pending state to screen readers. |
isDisabled | boolean | Whether the button is disabled. This prevents the user from interacting with the button. |
autoFocus | boolean | Whether the element should receive focus on render. |
children | ReactNode | The content to display inside the button. |
className | string | Additional CSS classes to apply to the button. |
style | CSSProperties | Inline styles to apply to the button. |
Events
| Name | Type | Description |
|---|---|---|
onPress | (e: PressEvent) → void | Handler that is called when the press is released over the target. |
onPressStart | (e: PressEvent) → void | Handler that is called when a press interaction starts. |
onPressEnd | (e: PressEvent) → void | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. |
onPressChange | (isPressed: boolean) → void | Handler that is called when the press state changes. |
onPressUp | (e: PressEvent) → void | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |
onFocus | (e: FocusEvent) → void | Handler that is called when the element receives focus. |
onBlur | (e: FocusEvent) → void | Handler that is called when the element loses focus. |
onFocusChange | (isFocused: boolean) → void | Handler that is called when the element's focus status changes. |
onKeyDown | (e: KeyboardEvent) → void | Handler that is called when a key is pressed. |
onKeyUp | (e: KeyboardEvent) → void | Handler that is called when a key is released. |
Layout
| Name | Type | Description |
|---|---|---|
slot | string | A slot name for the component. Slots allow the component to receive props from a parent component. |
Accessibility
| Name | Type | Description |
|---|---|---|
id | string | The element's unique identifier. |
excludeFromTabOrder | boolean | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. |
aria-label | string | Defines a string value that labels the current element. |
aria-labelledby | string | Identifies the element (or elements) that labels the current element. |
aria-describedby | string | Identifies the element (or elements) that describes the object. |
aria-details | string | Identifies the element (or elements) that provide a detailed, extended description for the object. |
aria-controls | string | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
aria-expanded | UnionTypeboolean | "true" | "false" | Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. |
aria-haspopup | UnionTypeboolean | "menu" | "listbox" | "tree" | "grid" | "dialog" | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
aria-pressed | UnionTypeboolean | "true" | "false" | "mixed" | Indicates the current "pressed" state of toggle buttons. |
Data attributes
| Name | Type | Description |
|---|---|---|
[data-hover] | boolean | |
[data-pressed] | boolean | |
[data-focused] | boolean | |
[data-focused-visible] | boolean | |
[data-disabled] | boolean | |
[data-pending] | boolean |
Accessibility
This component is based on the native button element and supports all of its props. It handles press interactions across mouse, touch, pen, and keyboard, normalizing behavior across browsers and platforms. It includes support for pressed states, disabled states, and accessible labelling via ARIA attributes.
Styling
The Button component is built with Tailwind CSS and supports full customization through the className prop. You can extend or override any of the default styles.