@litforge/icon-button

An icon-only button component with variants, sizes, loading state, and accessibility support, built with Lit.

Overview

The IconButton component provides a button that displays only an icon (or uses a slot for custom content) with support for different variants, sizes, loading states, and full accessibility.

Installation

npm install @litforge/icon-button
# or
pnpm add @litforge/icon-button
# or
yarn add @litforge/icon-button

Basic Usage

<script type="module">
  import '@litforge/icon-button';
</script>

<icon-button icon="✏️" label="Edit" @icon-button-click=${handleClick}></icon-button>

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | icon | string | '' | Icon character or emoji | | label | string | '' | Accessibility label (aria-label) | | variant | 'primary' \| 'secondary' \| 'danger' \| 'ghost' | 'ghost' | Button variant | | size | 'sm' \| 'md' \| 'lg' | 'md' | Button size | | disabled | boolean | false | Disabled state | | loading | boolean | false | Loading state with spinner |

Events

icon-button-click

Fired when the button is clicked.

Detail: { originalEvent: MouseEvent }

Examples

Basic Icon Button

<icon-button icon="✏️" label="Edit" @icon-button-click=${handleEdit}></icon-button>

Variants

<icon-button icon="✏️" variant="primary" label="Edit"></icon-button>
<icon-button icon="🗑️" variant="danger" label="Delete"></icon-button>
<icon-button icon="👁️" variant="secondary" label="View"></icon-button>
<icon-button icon="⚙️" variant="ghost" label="Settings"></icon-button>

Sizes

<icon-button icon="✏️" size="sm" label="Edit"></icon-button>
<icon-button icon="✏️" size="md" label="Edit"></icon-button>
<icon-button icon="✏️" size="lg" label="Edit"></icon-button>

Loading State

<icon-button icon="💾" label="Save" loading></icon-button>

With Custom Content (Slot)

<icon-button label="Custom" variant="primary">
  <svg width="16" height="16">...</svg>
</icon-button>

Styling

The component uses CSS variables for theming:

icon-button {
  --lf-icon-button-radius: 8px;
  --lf-icon-button-padding: 8px;
  --lf-icon-button-color: #111827;
  --lf-icon-button-primary-bg: #0b6efd;
  --lf-icon-button-primary-color: #ffffff;
  /* ... more variables */
}

TypeScript

import { IconButton, IconButtonVariant, IconButtonSize } from '@litforge/icon-button';

Accessibility

• Always provide a label prop for accessibility (used as aria-label)
• The button is keyboard accessible
• Loading state sets aria-busy="true"
• Disabled state properly prevents interaction

License

Part of the LitForge component library.