ShakibDShy

useButtonGroup

A hook for managing button group state and interactions

useButtonGroup Hook

The useButtonGroup hook provides state management and interaction handling for button groups, making it easy to create custom button group implementations.

Import

import { useButtonGroup } from 'react-button-pro';

Basic Usage

function CustomButtonGroup() {
  const groupProps = useButtonGroup({
    orientation: 'horizontal',
    spacing: 'md',
  });
 
  return (
    <div {...groupProps}>
      <button>Option 1</button>
      <button>Option 2</button>
      <button>Option 3</button>
    </div>
  );
}

Features

State Management

Handles selected state and group interactions

Keyboard Navigation

Arrow key navigation between buttons

Accessibility

ARIA roles and attributes for button groups

Customization

Flexible styling and behavior options

API Reference

Hook Parameters

interface UseButtonGroupProps {
  orientation?: 'horizontal' | 'vertical';
  spacing?: 'none' | 'sm' | 'md' | 'lg';
  selectedIndex?: number;
  onChange?: (index: number) => void;
  'aria-label'?: string;
  'aria-labelledby'?: string;
}

Return Value

interface UseButtonGroupReturn {
  role: 'group';
  'aria-orientation': 'horizontal' | 'vertical';
  onKeyDown: (event: React.KeyboardEvent) => void;
  ref: React.RefObject<HTMLDivElement>;
  [key: string]: any;
}

Examples

With Selection State

function SelectableButtonGroup() {
  const [selected, setSelected] = useState(0);
  
  const groupProps = useButtonGroup({
    selectedIndex: selected,
    onChange: setSelected,
  });
 
  return (
    <div {...groupProps}>
      {['Tab 1', 'Tab 2', 'Tab 3'].map((label, index) => (
        <button
          key={index}
          aria-selected={selected === index}
          onClick={() => setSelected(index)}
        >
          {label}
        </button>
      ))}
    </div>
  );
}

With Keyboard Navigation

function NavigableButtonGroup() {
  const groupProps = useButtonGroup({
    orientation: 'horizontal',
    'aria-label': 'Navigation',
  });
 
  return (
    <div {...groupProps}>
      <button>Previous</button>
      <button>Current</button>
      <button>Next</button>
    </div>
  );
}

With Custom Styling

function StyledButtonGroup() {
  const groupProps = useButtonGroup({
    spacing: 'lg',
  });
 
  return (
    <div 
      {...groupProps}
      className="flex gap-4 p-2 rounded-lg bg-gray-100"
    >
      <button className="px-4 py-2 rounded">Left</button>
      <button className="px-4 py-2 rounded">Middle</button>
      <button className="px-4 py-2 rounded">Right</button>
    </div>
  );
}

Best Practices

  1. State Management:

    • Handle selection state properly
    • Maintain controlled/uncontrolled modes
    • Consider group context
    • Clean up event listeners

  2. Keyboard Navigation:

    • Support arrow key navigation
    • Handle focus management
    • Consider focus trapping
    • Support Home/End keys

  3. Accessibility:

    • Provide descriptive labels
    • Use proper ARIA roles
    • Support screen readers
    • Handle focus indicators

  4. Customization:

    • Allow flexible styling
    • Support different orientations
    • Enable custom spacing
    • Handle dynamic content

Examples

With Form Integration

function FormButtonGroup() {
  const groupProps = useButtonGroup();
 
  return (
    <form>
      <div {...groupProps} role="radiogroup">
        <button type="button" role="radio">
          Option 1
        </button>
        <button type="button" role="radio">
          Option 2
        </button>
      </div>
    </form>
  );
}

With Icons

function IconButtonGroup() {
  const groupProps = useButtonGroup();
 
  return (
    <div {...groupProps}>
      <button>
        <PrevIcon /> Previous
      </button>
      <button>
        Next <NextIcon />
      </button>
    </div>
  );
}

With Dynamic Content

function DynamicButtonGroup() {
  const [items, setItems] = useState(['A', 'B', 'C']);
  const groupProps = useButtonGroup();
 
  return (
    <div {...groupProps}>
      {items.map((item, index) => (
        <button key={index}>
          {item}
        </button>
      ))}
    </div>
  );
}
  • useButton - For individual button state management
  • ButtonGroup component - Pre-built button group component
  • Button component - Base button component

Last updated on

Previous

useButton

Next

Changelog

On this page