# components/IconButton (zidane-ui)

Import: `import { … } from 'zidane-ui'`. Source: [ui/src/components/IconButton.tsx](https://github.com/Tahul/zidane/blob/main/ui/src/components/IconButton.tsx).

## Components

### `IconButton`

Component.

Renders a square icon button with an accessible label. Hover and `active` states lift it
to the raised chip. Use `render` to draw another element, such as a link, with the same
look. The ref goes to the `button`.

```ts
const IconButton: ForwardRefExoticComponent<IconButtonProps & RefAttributes<HTMLButtonElement>>
```

**Props**

- `active?` (`boolean`, from `IconButtonLook`): Toggled on / open: shows as the raised chip.
- `children?` (`ReactNode`): Badges and overlays (an unseen dot, a spinner) over the glyph.
- `icon` (`ReactNode`): An icon class (`i-ph-*`) or a node (`SwapIcon`, an svg).
- `label` (`string`): Accessible name and default tooltip. Required, since the button has no text.
- `overlay?` (`boolean`, from `IconButtonLook`): Room for badges / overlays positioned over the glyph.
- `render?` (`(props: IconButtonRenderProps) => ReactElement`): Render another element with the button's look (a link).
- `size?` (`'xs' | 'sm' | 'md' | 'lg'`, from `IconButtonLook`, default `'md'`): Button size.
- `tone?` (`'danger' | 'neutral'`, from `IconButtonLook`, default `'neutral'`): Colour of the glyph. `danger` turns it red on hover.

Source: [ui/src/components/IconButton.tsx:83](https://github.com/Tahul/zidane/blob/main/ui/src/components/IconButton.tsx#L83)

## Functions

### `iconButtonClass`

Function.

The IconButton look as a class string, for elements that can't be the component.

```ts
function iconButtonClass(look?: IconButtonLook): string
```

**Parameters**

- `look?` (`IconButtonLook`, default `{}`): The size, tone and overlay options of the look. Defaults to a `md`, `neutral`
  button without overlay.

**Returns** `string`

Source: [ui/src/components/IconButton.tsx:47](https://github.com/Tahul/zidane/blob/main/ui/src/components/IconButton.tsx#L47)

## Interfaces

### `IconButtonLook`

Interface.

Visual options of an [`IconButton`](https://zidane.si/docs/reference/ui-components-icon-button.md#IconButton), shared with [`iconButtonClass`](https://zidane.si/docs/reference/ui-components-icon-button.md#iconButtonClass).

```ts
interface IconButtonLook
```

**Properties**

- `active?` (`boolean`): Toggled on / open: shows as the raised chip.
- `overlay?` (`boolean`): Room for badges / overlays positioned over the glyph.
- `size?` (`'xs' | 'sm' | 'md' | 'lg'`, default `'md'`): Button size.
- `tone?` (`'danger' | 'neutral'`, default `'neutral'`): Colour of the glyph. `danger` turns it red on hover.

Source: [ui/src/components/IconButton.tsx:24](https://github.com/Tahul/zidane/blob/main/ui/src/components/IconButton.tsx#L24)

### `IconButtonProps`

Interface.

Visual options of an [`IconButton`](https://zidane.si/docs/reference/ui-components-icon-button.md#IconButton), shared with [`iconButtonClass`](https://zidane.si/docs/reference/ui-components-icon-button.md#iconButtonClass).

```ts
interface IconButtonProps extends IconButtonLook, Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'>
```

**Properties**

- `active?` (`boolean`, from `IconButtonLook`): Toggled on / open: shows as the raised chip.
- `children?` (`ReactNode`): Badges and overlays (an unseen dot, a spinner) over the glyph.
- `icon` (`ReactNode`): An icon class (`i-ph-*`) or a node (`SwapIcon`, an svg).
- `label` (`string`): Accessible name and default tooltip. Required, since the button has no text.
- `overlay?` (`boolean`, from `IconButtonLook`): Room for badges / overlays positioned over the glyph.
- `render?` (`(props: IconButtonRenderProps) => ReactElement`): Render another element with the button's look (a link).
- `size?` (`'xs' | 'sm' | 'md' | 'lg'`, from `IconButtonLook`, default `'md'`): Button size.
- `tone?` (`'danger' | 'neutral'`, from `IconButtonLook`, default `'neutral'`): Colour of the glyph. `danger` turns it red on hover.

Source: [ui/src/components/IconButton.tsx:67](https://github.com/Tahul/zidane/blob/main/ui/src/components/IconButton.tsx#L67)

### `IconButtonRenderProps`

Interface.

Props `IconButtonProps.render` receives to spread onto the element it renders.

```ts
interface IconButtonRenderProps
```

**Properties**

- `aria-label` (`string`): Accessible name, taken from `label`.
- `children` (`ReactNode`): The icon followed by any badges or overlays.
- `className` (`string`): Classes carrying the button's look, merged with the caller's `className`.
- `data-active?` (`''`): Set to an empty string while the button is `active`, otherwise absent.
- `title` (`string`): Tooltip text. The `title` prop, or `label` when none is given.

Source: [ui/src/components/IconButton.tsx:54](https://github.com/Tahul/zidane/blob/main/ui/src/components/IconButton.tsx#L54)

## Types

### `IconButtonSize`

Type.

Size of an [`IconButton`](https://zidane.si/docs/reference/ui-components-icon-button.md#IconButton): `xs` (20px), `sm` (24px), `md` (28px) or `lg` (32px).

```ts
type IconButtonSize = keyof typeof SIZES
```

Source: [ui/src/components/IconButton.tsx:21](https://github.com/Tahul/zidane/blob/main/ui/src/components/IconButton.tsx#L21)