# Icon Button (`icon-button`) - SignalOS widget

> Icon-only button with an accessible label and optional tooltip.

- **Version:** 0.2.1
- **Kind:** widget · **Category:** data-display
- **Install:** `npx shadcn@latest add @signalos/icon-button`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/utils, @signalos/button, @signalos/tooltip
- **npm dependencies:** lucide-react@^1.7.0
- **Files installed:** `src/components/widgets/icon-button/IconButton.tsx`, `src/components/widgets/icon-button/IconButton.types.ts`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
import { IconButton } from "@/components/widgets/icon-button/IconButton"
```

## Example

```tsx
// Example: wiring the shell in a plain React app (router-agnostic).
// In Next.js, pass `activePath={usePathname()}` and a Link adapter:
//   LinkComponent={({ href, ...p }) => <Link href={href} {...p} />}

import { Plus } from "lucide-react"

import { IconButton } from "./IconButton"

export default function Example() {
  return (
    <div className="flex  overflow-hidden rounded-lg  [&_aside]:!flex [&_aside]:h-full">
      <div className="flex flex-wrap gap-2">
        <IconButton
          icon={<Plus className="h-4 w-4" />}
          label="Add"
          onClick={() => {}}
        />
      </div>
    </div>
  )
}
```

## Props

### `BaseButtonProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `type` | `"button" \| "submit" \| "reset" \| undefined` | no | - | Specifies the button behavior.  - `"button"` → Performs a normal button action (default). - `"submit"` → Submits the parent form. - `"reset"` → Resets all form fields to their initial values. |
| `disabled` | `boolean \| undefined` | no | - | Determines whether the button is disabled.  When `true`: - The button cannot be clicked. - The click handler is not executed. - The button is rendered in a disabled state. |
| `onClick` | `MouseEventHandler<HTMLButtonElement> \| undefined` | no | - | Callback function executed when the button is clicked.  Example: ```tsx onClick={() => console.log("Button clicked")} ``` |
| `name` | `string \| undefined` | no | - | Name of the button.  Primarily used when the button is inside a form and its value needs to be submitted. |
| `value` | `string \| undefined` | no | - | Value submitted with the button when used as a form submit button. |

### `IconButtonProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `icon` | `ReactNode` | yes | - | Icon displayed inside the button.  Accepts any valid React element.  Examples: ```tsx <Search /> <Plus /> <Trash2 /> ``` |
| `label` | `string` | yes | - | Accessible label describing the button's purpose.  This is used for accessibility and may also be used as tooltip text when tooltips are enabled.  Examples: - `"Search"` - `"Delete"` - `"Add User"` |
| `size` | `"icon-xs" \| "icon-sm" \| "icon" \| "icon-lg" \| undefined` | no | `"icon"` | Controls the size of the icon button.  Available sizes: - `icon-xs` → Extra Small - `icon-sm` → Small - `icon` → Default/Medium - `icon-lg` → Large |
| `variant` | `"default" \| "destructive" \| "secondary" \| "outline" \| "ghost" \| undefined` | no | `"ghost"` | Controls the visual style of the button.  Available variants: - `default` → Primary button - `secondary` → Secondary button - `outline` → Transparent background with border - `ghost` → Minimal background - `destructive` → Used for delete or dangerous actions |
| `className` | `string \| undefined` | no | - | Additional CSS or Tailwind utility classes.  Useful for customizing spacing, positioning, or overriding default styles.  Example: ```tsx className="ml-2 rounded-full" ``` |
| `showTooltip` | `boolean \| undefined` | no | `true` | Whether a tooltip should be displayed when hovering over the button. |
| `tooltipDelay` | `number \| undefined` | no | `200` | Delay before showing the tooltip.  Value is specified in milliseconds.  Examples: - `0` → Show immediately - `300` → Show after 300ms - `500` → Show after half a second |
| `data-testid` | `string \| undefined` | no | - | Test identifier rendered as `data-testid` on the root element. |
| `type` | `"button" \| "submit" \| "reset" \| undefined` | no | - | Specifies the button behavior.  - `"button"` → Performs a normal button action (default). - `"submit"` → Submits the parent form. - `"reset"` → Resets all form fields to their initial values. |
| `disabled` | `boolean \| undefined` | no | - | Determines whether the button is disabled.  When `true`: - The button cannot be clicked. - The click handler is not executed. - The button is rendered in a disabled state. |
| `onClick` | `MouseEventHandler<HTMLButtonElement> \| undefined` | no | - | Callback function executed when the button is clicked.  Example: ```tsx onClick={() => console.log("Button clicked")} ``` |
| `name` | `string \| undefined` | no | - | Name of the button.  Primarily used when the button is inside a form and its value needs to be submitted. |
| `value` | `string \| undefined` | no | - | Value submitted with the button when used as a form submit button. |

## Changelog

# icon-button

## 0.2.1

- Fix three `@default` JSDoc tags in `IconButton.types.ts` that contradicted
  the component's actual defaults (catalog docs only; no behavior change):
  `variant` is `"ghost"` (was documented `"default"`), `showTooltip` is
  `true` (was documented `false`), `tooltipDelay` is `200` (was documented
  `0`).

## 0.2.0

- **Breaking:** rename the `testId` prop to `data-testid` to match the rest
  of the registry and the DOM attribute name.

## 0.1.2

- Content sync fix to bring source in line with published registry payload.


## 0.1.1

- Minor updates.

## 0.1.0

- Initial release.