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

npm install @polarityio/pi-button

Peer Dependencies

• lit ^3.0.0

Usage

import '@polarityio/pi-button';

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.

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

License

MIT