npm package: @polarityio/pi-button
Description: Versatile button component with primary, secondary, tertiary, and entity types, icon support, and disabled tooltip
Latest version: 1.0.3

# Polarity Integration Component Library

## Button Component

A versatile button component supporting primary, secondary, tertiary, and entity types with optional prefix/suffix icons, danger variant, and disabled tooltip.

## Installation

```bash
npm install @polarityio/pi-button
```

### Peer Dependencies

- [lit](https://lit.dev/) ^3.0.0

## Usage

```javascript
import '@polarityio/pi-button';
```

```javascript
import { html } from 'lit';
import { faGear, faTrash } from '@fortawesome/free-solid-svg-icons';

html`
  <!-- Primary button -->
  <pi-button label="Submit"></pi-button>

  <!-- Secondary button with icon -->
  <pi-button type="secondary" label="Settings" .prefixIcon=${faGear}></pi-button>

  <!-- Danger variant -->
  <pi-button variant="danger" label="Delete"></pi-button>

  <!-- Icon-only button -->
  <pi-button icon-only .prefixIcon=${faTrash}></pi-button>

  <!-- Disabled with tooltip -->
  <pi-button disabled disabled-tooltip="You must select an item first" label="Continue"></pi-button>
`;
```

### Button Types

| Type | Description |
| --- | --- |
| `primary` | Solid background with inverse text — the default call-to-action style |
| `secondary` | Light background with border — for secondary actions |
| `tertiary` | Minimal transparent button — for low-emphasis actions |
| `entity` | Semi-transparent white background — for use on entity cards |

## API Reference

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'primary' \| 'secondary' \| 'tertiary' \| 'entity'` | `'primary'` | Button type/style variant |
| `variant` | `'primary' \| 'danger'` | `'primary'` | Visual variant — use `'danger'` for destructive actions |
| `label` | `string` | `''` | Button label text (can also use the default slot) |
| `disabled` | `boolean` | `false` | Disables the button and prevents click events |
| `selected` | `boolean` | `false` | Sets `aria-pressed` and applies selected styling |
| `condensed` | `boolean` | `false` | Renders the button in a compact size |
| `overlay` | `boolean` | `false` | Tertiary overlay mode for use on media backgrounds |
| `prefixIcon` | `IconDefinition \| undefined` | `undefined` | FontAwesome icon rendered before the label |
| `suffixIcon` | `IconDefinition \| undefined` | `undefined` | FontAwesome icon rendered after the label |
| `iconOnly` | `boolean` | `false` | Hides the label and renders a square icon-only button |
| `name` | `string` | `''` | HTML button name attribute for form submission |
| `value` | `string` | `''` | HTML button value attribute for form submission |
| `disabledTooltip` | `string` | `''` | Tooltip text shown on hover when the button is disabled |

### Events

| Event Name | Detail | Description |
| --- | --- | --- |
| `pi-click` | `{ originalEvent: Event }` | Fired when the button is clicked. Not fired if the button is disabled. |

### Slots

| Slot Name | Description |
| --- | --- |
| *(default)* | Primary content slot for button label. Overrides the `label` property. |
| `prefix-icon` | Custom prefix icon content. Overrides the `prefixIcon` property. |
| `suffix-icon` | Custom suffix icon content. Overrides the `suffixIcon` property. |

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--pi-button-font-family` | `var(--pi-font-family-base)` | Font family |
| `--pi-button-font-size` | `var(--pi-size-font-base)` | Font size |
| `--pi-button-font-weight` | `var(--pi-font-weight-medium)` | Font weight |
| `--pi-button-padding-vertical` | `var(--pi-size-spacing-sm)` | Vertical padding |
| `--pi-button-padding-horizontal` | `var(--pi-size-spacing-lg)` | Horizontal padding |
| `--pi-button-gap` | `var(--pi-size-spacing-sm)` | Gap between icon and label |
| `--pi-button-border-radius` | `var(--pi-size-radius-base)` | Border radius |
| `--pi-button-min-height` | `32px` | Minimum button height |
| `--pi-button-transition` | `var(--pi-transition-fast)` | Transition timing |
| `--pi-button-icon-size` | `14px` | Icon size |
| `--pi-button-icon-color` | `currentColor` | Icon color |

## Theming

Customize the appearance using CSS custom properties. This component uses design tokens from `@polarityio/pi-shared` for consistent theming across the component library.

```css
pi-button {
  --pi-button-font-size: 1rem;
  --pi-button-border-radius: 8px;
  --pi-button-padding-horizontal: 24px;
}
```

## License

MIT