Skip to main content

Button

A headless, accessible button component that provides complete keyboard support and toggle functionality.

Live Demo​

JavaScript
<div className='button-demo-container'>
    <Button className="button">
      button
    </Button>
  </div>

Features​

  • ✅ Polymorphic rendering via as prop — renders as any HTML element or component
  • ✅ Toggle button functionality with controlled and uncontrolled modes
  • ✅ Loading state management with isLoading prop
  • ✅ Auto-focus support on mount
  • ✅ Disabled state management

Import​

import { Button } from '@turkish-technology/spar';

Anatomy​

The Button is a single component that can be configured for different use cases:

Parts
ButtonInteractive button element

Structure​

<Button>Button content</Button>

Data Flow:

  • Single component with complete keyboard support and toggle functionality
  • Manages its own state or accepts controlled props
  • Provides comprehensive accessibility features

Code Examples​

Basic Usage​

Simple button with click handler:

function BasicButton() {
const handleClick = () => {
console.log('Button clicked!');
};

return <Button onClick={handleClick}>Click me</Button>;
}

Toggle Button​

Create a toggle button with controlled state:

function ToggleButton() {
const [isToggled, setIsToggled] = useState(false);

return (
<Button isPressed={isToggled} onPressedChange={setIsToggled}>
{isToggled ? 'On' : 'Off'}
</Button>
);
}

Loading State​

Button with loading state:

function LoadingButton() {
const [isLoading, setIsLoading] = useState(false);

const handleSubmit = async () => {
setIsLoading(true);
try {
await new Promise(resolve => setTimeout(resolve, 2000));
} finally {
setIsLoading(false);
}
};

return (
<Button onClick={handleSubmit} isLoading={isLoading}>
{isLoading ? 'Submitting...' : 'Submit Form'}
</Button>
);
}

Polymorphic Rendering​

Render as different HTML elements:

function PolymorphicButtons() {
return (
<>
{/* Render as anchor tag */}
<Button as="a" href="/dashboard">
Go to Dashboard
</Button>

{/* Render as div with button role */}
<Button as="div">Custom Element Button</Button>

{/* Render with submit type */}
<Button type="submit">Submit Form</Button>
</>
);
}

While disabled or isLoading, a non-native element cancels the click's default action, and a plain as='a' additionally drops its href, so an inert link cannot navigate (aria-disabled, tabIndex and aria-busy are unchanged).

Auto-focus and Disabled States​

Button with auto-focus and disabled state management:

function AccessibilityExample() {
const [disabled, setDisabled] = useState(false);

return (
<>
<Button autoFocus disabled={disabled}>
{disabled ? 'Cannot click' : 'Auto-focused button'}
</Button>

<Button onClick={() => setDisabled(!disabled)}>
{disabled ? 'Enable' : 'Disable'} first button
</Button>
</>
);
}

API Reference​

Button​

A headless, accessible button component with complete keyboard support and toggle functionality.

Props

NameTypeDefaultDescription
as?React.ElementType"button"The element type to render as
type?"button" | "submit" | "reset""button"Button type (only applies when as="button")
disabled?booleanfalseDisabled state - properly announced to screen readers
autoFocus?booleanfalseWhether the button should receive focus when first rendered
isLoading?booleanfalseLoading state with screen reader support
isPressed?booleanundefinedToggle state - when defined, creates a toggle button
onPressedChange?(pressed: boolean) => voidundefinedCallback fired when toggle state changes
children?React.ReactNodeundefinedComponent content
onClick?React.MouseEventHandler<HTMLButtonElement>undefinedClick event handler
onKeyDown?React.KeyboardEventHandler<HTMLButtonElement>undefinedKeyboard event handler
className?stringundefinedCSS class names
style?React.CSSPropertiesundefinedInline styles
ref?React.Ref<HTMLElement>undefinedRef to the underlying element

Events

NameParametersDescriptionWhen Triggered
onClick(event: React.MouseEvent<HTMLButtonElement>)Mouse click eventUser clicks the button
onKeyDown(event: React.KeyboardEvent<HTMLButtonElement>)Keyboard eventUser presses a key while button is focused
onPressedChange(pressed: boolean)Toggle state changeToggle button state changes (controlled or uncontrolled)

HTML Attributes

AttributeValuePurpose
data-disabled""Styling hook for disabled state
data-loading""Styling hook for loading state
data-pressed""Present when component is in toggle mode and currently pressed
data-autofocus""Styling hook for auto-focused buttons

Keyboard Interactions​

Complete keyboard behavior for the Button component:

KeyActionContextNotes
TabNavigate to buttonAlwaysMoves focus to the button (unless disabled)
Shift + TabNavigate away from buttonAlwaysMoves focus away from the button
EnterActivate buttonButton focusedTriggers click handler and toggle state change
SpaceActivate buttonButton focusedAlternative activation method, same as Enter

Accessibility Notes:

  • Disabled buttons have tabIndex={-1} and cannot receive focus
  • Loading buttons remain focusable and announce loading state to screen readers
  • Toggle buttons properly announce their pressed state via aria-pressed
  • Screen reader users receive loading announcements via aria-live="polite"
  • Polymorphic rendering maintains button semantics with proper role attribute