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

Preview

import { Button } from '@sprocketui/react';

function Example() {
  return (
    <Button
      variant="primary"
      className="px-4 py-2 rounded-lg"
      onPress={() => alert('Clicked!')}
    >
      Click me
    </Button>
  );
}

Anatomy

Buttons consist of a clickable area usually containing a textual label or an icon that users can click to perform an action. In addition, keyboard users may activate buttons using the Space or Enter keys.

States

{/* Loading state */}
<Button isPending>Loading...</Button>
 
{/* Disabled state */}
<Button isDisabled>Disabled</Button>

API Reference

Props

Name	Type	Default	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.
`variant`	`'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'`	`'primary'`	The visual style variant of the button.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	The size of the button.
`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	Default	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	Default	Description
`slot`	`string`	`—`	A slot name for the component. Slots allow the component to receive props from a parent component.

Accessibility

Name	Type	Default	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`	`boolean \| "true" \| "false"`	`—`	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| "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`	`boolean \| "true" \| "false" \| "mixed"`	`—`	Indicates the current "pressed" state of toggle buttons.

Accessibility

The Button component follows WAI-ARIA best practices:

Uses semantic <button> element
Supports all ARIA attributes for enhanced accessibility
Disabled and pending states are properly communicated to assistive technologies
Keyboard navigation works as expected (Space/Enter to activate)
Focus management is handled automatically

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.