# ItemButton

An interactive button component built on top of `Item` that provides all the layout and styling capabilities of Item with full button functionality. ItemButton supports actions, links, form submissions, and all the advanced features like hotkeys, tooltips, and selection states.

## When to Use

- For buttons that need structured content with icons, descriptions, or prefixes/suffixes
- When you need button functionality with the flexible layout capabilities of Item
- For interactive items in lists, menus, or toolbars that need consistent styling
- When building buttons that support features like keyboard shortcuts or overflow tooltips
- As an alternative to traditional buttons when you need more layout control

## Component

---

### Properties

### Base Properties

Supports [Base properties](/BaseProperties)

### Item Properties

ItemButton inherits all properties from [Item](../content/Item.md), including:
- Layout properties: `icon`, `rightIcon`, `prefix`, `suffix`, `description`, `descriptionPlacement`
- Interactive properties: `hotkeys`, `tooltip`, `isSelected`
- Styling properties: `size`, `type`, `theme`, `styles`

### Content Properties

#### actions
- **Type**: `ReactNode`
- **Description**: Inline action buttons displayed on the right side of the button. Use `ItemButton.Action` for consistent styling. Actions automatically inherit the parent button's `type` prop and the component reserves space to prevent content overlap.

### Action Properties

#### onPress
- **Type**: `(e: PressEvent) => void`
- **Description**: Callback fired when the button is pressed via mouse, keyboard, or touch

#### to
- **Type**: `string`
- **Description**: URL for link behavior - when provided, the button acts as a link

#### buttonType
- **Type**: `'button' | 'submit' | 'reset'`
- **Description**: HTML button type attribute for form integration
- **Default**: `'button'`

#### isDisabled
- **Type**: `boolean`
- **Description**: Whether the button is disabled and non-interactive

### Style Properties

These properties allow direct style application without using the `styles` prop: `width`, `height`, `padding`, `margin`, `color`, `fill`, `opacity`, `display`, `position`, `zIndex`, `gap`, `flow`, `placeItems`, `placeContent`, `alignItems`, `justifyContent`, `border`, `radius`, `shadow`, `overflow`.

### Modifiers

Inherits all modifiers from [Item](../content/Item.md) plus:

| Modifier | Type | Description |
|----------|------|-------------|
| disabled | `boolean` | Applied when the button is disabled |
| pressed | `boolean` | Applied during button press interaction |

## Variants

### Types

- `primary` - Primary button with prominent styling for main actions
- `secondary` - Secondary button with moderate emphasis
- `outline` - Button with border outline and transparent background
- `neutral` - Neutral styled button for subtle actions
- `clear` - Transparent button with minimal visual weight
- `link` - Link-styled button that looks like a text link

### Themes

- `default` - Standard appearance with default colors
- `danger` - Red theme for destructive actions (delete, remove, etc.)
- `success` - Green theme for positive actions (save, confirm, etc.)
- `special` - Special theme with unique styling for standout actions

### Sizes

- `xsmall` - Extra small size for compact interfaces
- `small` - Small size for dense layouts  
- `medium` - Default size for most use cases
- `large` - Large size for prominent actions
- `xlarge` - Extra large size for hero actions
- `inline` - Inline size that adapts to content

## Examples

### Basic Button

```jsx
<ItemButton onPress={() => console.log('Clicked')}>
  Click me
</ItemButton>
```

### Button with Icons

```jsx
<ItemButton 
  icon={<IconFile />}
  rightIcon={<IconExternalLink />}
  onPress={handleOpen}
>
  Open File
</ItemButton>
```

### Link Button

```jsx
<ItemButton to="/docs">
  Go to Documentation
</ItemButton>
```

### Button with Hotkey

```jsx
<ItemButton 
  hotkeys="cmd+s"
  onPress={handleSave}
  type="primary"
>
  Save Document
</ItemButton>
```

### Form Submit Button

```jsx
<ItemButton 
  buttonType="submit"
  type="primary"
  icon={<IconCheck />}
>
  Submit Form
</ItemButton>
```

### Button with Selection State

```jsx
<ItemButton 
  isSelected={isSelected}
  onPress={() => setIsSelected(!isSelected)}
>
  Toggle Selection
</ItemButton>
```

### Button with Actions

ItemButton supports inline actions that appear on the right side. Use the `ItemButton.Action` compound component for consistent styling:

```jsx
<ItemButton 
  icon={<IconFile />}
  actions={
    <>
      <ItemButton.Action icon={<IconEdit />} aria-label="Edit" onPress={handleEdit} />
      <ItemButton.Action icon={<IconTrash />} aria-label="Delete" onPress={handleDelete} />
    </>
  }
  onPress={handleOpen}
>
  Document with Actions
</ItemButton>
```

Actions automatically inherit the parent button's `type` prop and adjust their styling accordingly. The component reserves space for actions to prevent content overlap.

## Accessibility

### Keyboard Navigation

- `Tab` - Moves focus to the button
- `Space/Enter` - Activates the button
- Custom hotkeys - Trigger button action when hotkeys are specified
- `Escape` - Removes focus when pressed (standard browser behavior)

### Screen Reader Support

- Button announces as "button" to screen readers
- Link buttons announce as "link" when `to` prop is provided
- Button state is announced (pressed, disabled, selected)
- Hotkey information is included in accessible description

### ARIA Properties

- `aria-label` - Provides accessible label when text content isn't descriptive enough
- `aria-disabled` - Indicates disabled state
- `aria-pressed` - Indicates toggle state for toggle buttons
- `role` - Automatically set to "button" or "link" based on props

## Best Practices

1. **Do**: Use clear, action-oriented text
   ```jsx
   <ItemButton onPress={handleSave} type="primary">
     Save Changes
   </ItemButton>
   ```

2. **Do**: Add hotkeys for frequently used actions
   ```jsx
   <ItemButton hotkeys="cmd+s" onPress={handleSave}>
     Save Document
   </ItemButton>
   ```

3. **Do**: Use appropriate button types for forms
   ```jsx
   <ItemButton buttonType="submit" type="primary">
     Submit Form
   </ItemButton>
   ```

4. **Do**: Use `ItemButton.Action` for inline actions
   ```jsx
   <ItemButton 
     icon={<IconFile />}
     actions={
       <>
         <ItemButton.Action icon={<IconEdit />} aria-label="Edit" />
         <ItemButton.Action icon={<IconTrash />} aria-label="Delete" />
       </>
     }
     onPress={handleOpen}
   >
     Open Document
   </ItemButton>
   ```

5. **Don't**: Use vague or unclear button text
   ```jsx
   {/* Avoid this - unclear what "OK" does */}
   <ItemButton onPress={handleAction}>OK</ItemButton>
   ```

6. **Don't**: Add too many actions (limit to 2-3 for clarity)
   ```jsx
   {/* Avoid this - too many action buttons */}
   <ItemButton 
     actions={
       <>
         <ItemButton.Action icon={<IconEdit />} aria-label="Edit" />
         <ItemButton.Action icon={<IconCopy />} aria-label="Copy" />
         <ItemButton.Action icon={<IconShare />} aria-label="Share" />
         <ItemButton.Action icon={<IconTrash />} aria-label="Delete" />
       </>
     }
   >
     Button with too many actions
   </ItemButton>
   ```

7. **Don't**: Overcrowd buttons with too many visual elements
   ```jsx
   {/* Avoid this - too many competing elements */}
   <ItemButton 
     icon={<IconA />}
     rightIcon={<IconB />}
     prefix="Pre"
     suffix="Suf"
     description="Long description"
   >
     Overcrowded Button
   </ItemButton>
   ```

8. **Accessibility**: Always ensure buttons have clear, descriptive labels, proper keyboard support, and provide `aria-label` for action buttons

## Integration with Forms

ItemButton integrates seamlessly with forms when using the `buttonType` prop:

```jsx
<form onSubmit={handleSubmit}>
  <TextInput name="email" label="Email" />
  <ItemButton buttonType="submit" type="primary">
    Sign In
  </ItemButton>
  <ItemButton buttonType="reset" type="outline">
    Clear Form
  </ItemButton>
</form>
```

## Related Components

- [Item](../content/Item.md) - The foundational component that ItemButton extends
- ItemButton.Action - Action button component for inline actions (also available as `Item.Action`, `Menu.Item.Action`, etc.)
- [Button](./Button.md) - Traditional button component for simpler use cases
- [Link](./Link.md) - Text link component for navigation
- [Menu.Item](./Menu.md) - Menu item component that also uses Item
