---
title: IconButton
description: Trigger actions with accessible square icon buttons.
---

import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';

import IconButtonReference from '/snippets/ui/generated/input/icon-button.mdx';

`IconButton` composes [Button](/ui/primitives/input/button) with a square surface. Pass the icon as children and provide an `aria-label` describing the action. Icon content is decorative and hidden from assistive technology.

## Usage

```tsx
import { IconButton } from 'twenty-ui/components';
import { IconPlus } from 'twenty-ui/icon';

export const CreateRecordButton = () => (
  <IconButton
    aria-label="Create record"
    variant="solid"
    color="accent"
    size="sm"
  >
    <IconPlus />
  </IconButton>
);
```

Sizes are `sm` (24px) and `md` (32px). The defaults are `md`, `outline`, and `neutral`. Variants and colors match Button.

<StoryEmbed
  title="Icon button example"
  storyId="ui-components-iconbutton--catalog"
  height={620}
/>

## Tooltip

Add `tooltip` to show text on hover and keyboard focus. Keep `aria-label` as the accessible name of the action. Disabled and loading buttons retain hover tooltips.

```tsx
import { IconButton } from 'twenty-ui/components';
import { IconSearch } from 'twenty-ui/icon';

export const SearchRecordsButton = () => (
  <IconButton aria-label="Search" tooltip="Search records" variant="ghost">
    <IconSearch />
  </IconButton>
);
```

<StoryEmbed
  title="Icon button with tooltip"
  storyId="ui-components-iconbutton--tooltip"
  height={180}
/>

The tooltip defaults to the bottom, with a 1000ms delay and a 5px offset. Use `tooltipPlace`, `tooltipDelay`, and `tooltipOffset` to adjust it. Omitting `tooltip` renders the button directly.

## State ownership

Your application supplies `loading` and `disabled`. Both prevent activation. Loading preserves the square dimensions and accessible label. The button does not track a selected value or set loading automatically after a click. Native keyboard focus follows the browser; use `aria-pressed` when your application owns a toggle state.

## Grouped actions

```tsx
import { ButtonGroup } from 'twenty-ui/primitives/input';
import { IconButton } from 'twenty-ui/components';
import { IconPlus, IconSearch } from 'twenty-ui/icon';

export const RecordActions = () => (
  <ButtonGroup aria-label="Record actions" size="sm" variant="outline">
    <IconButton aria-label="Search records">
      <IconSearch />
    </IconButton>
    <IconButton aria-label="Create record">
      <IconPlus />
    </IconButton>
  </ButtonGroup>
);
```

[ButtonGroup](/ui/primitives/input/button-group) supplies size, variant, color, and adjoining corners. Individual buttons do not need a position prop.

## Links and forms

Use `href` to render an anchor. The caller can provide a custom `render` element, including its own router link. Supply `href` to select link semantics; the renderer must preserve an anchor. Without `href`, preserve a native button. Neither `nativeButton` nor `role` is part of the public button interface. Disabled links cannot activate. Routing stays in the application.

Native attributes, event handlers, refs, and render composition pass through to Button. The default is `type="button"`; set `type="submit"` explicitly for form submission.

## Props

<IconButtonReference />