The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: IconButton
description: Trigger actions with accessible icon buttons.
---
import { PageBanner } from "/snippets/page-banner.mdx"
import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import IconButtonReference from '/snippets/ui/generated/components/input/icon-button.mdx';
## Overview
`IconButton` composes [Button](/ui/primitives/input/button) with a square or round surface. Pass the icon as children and provide an accessible name with `aria-label` or `aria-labelledby`. Icon content is decorative and hidden from assistive technology.
<StoryEmbed
storyId="ui-components-iconbutton--display"
title="Icon button with an accessible name"
height={110}
/>
## Usage
```tsx
import { IconButton } from 'twenty-ui/components/input';
import { IconSearch } from 'twenty-ui/icon';
export const SearchButton = () => (
<IconButton aria-label="Search">
<IconSearch />
</IconButton>
);
```
Sizes are `xs` (20px), `sm` (24px), and `md` (32px). The defaults are `md`, `outline`, and `neutral`. Variants and colors match Button. Use `shape="round"` for a circular button; the default shape is `square`.
## Visual options
Compare one visual choice at a time. Use the named tooltip, elevated, and grouped examples for composition.
<StoryEmbed
storyId="ui-components-iconbutton--catalog"
title="Icon button variants, colors, sizes, shapes, elevation, and states"
height={810}
/>
## Accessible names
Use `aria-label` for a name supplied directly on the control. When visible text already names the action, use `aria-labelledby` to reference it instead. At least one naming prop is required.
```tsx
import { IconButton } from 'twenty-ui/components/input';
import { IconSearch } from 'twenty-ui/icon';
import { Text } from 'twenty-ui/primitives/typography';
export const LabelledSearchButton = () => (
<Text style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
<Text render={<span />} id="records-search-label">
Search records
</Text>
<IconButton aria-labelledby="records-search-label" tooltip="Find a record">
<IconSearch />
</IconButton>
</Text>
);
```
<StoryEmbed
title="Icon button named by visible text"
storyId="ui-components-iconbutton--labelled-by"
height={140}
/>
## Tooltip
Add `tooltip` to show text on hover and keyboard focus. Keep `aria-label` or `aria-labelledby` as the accessible name of the action. Disabled and loading buttons retain hover tooltips.
```tsx
import { IconButton } from 'twenty-ui/components/input';
import { IconSearch } from 'twenty-ui/icon';
export const SearchRecordsButton = () => (
<IconButton aria-label="Search" tooltip="Search records">
<IconSearch />
</IconButton>
);
```
<StoryEmbed
title="Icon button with tooltip"
storyId="ui-components-iconbutton--tooltip-documentation"
height={140}
/>
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.
## Elevated actions
Use `elevated` to add a shadow and backdrop blur. The default neutral outline button also gains a bordered surface with matching icon and interaction colors. Other variants and semantic colors keep their existing palette.
`elevated` defaults to `false`. It does not change positioning, visibility, or size. The size remains `md` (32px) by default; set `size="sm"` for a 24px control.
```tsx
import { IconButton } from 'twenty-ui/components/input';
import { IconPlus } from 'twenty-ui/icon';
export const AddWidgetButton = () => (
<IconButton elevated size="sm" aria-label="Add widget">
<IconPlus />
</IconButton>
);
```
<StoryEmbed
title="Elevated icon action"
storyId="ui-components-iconbutton--elevated"
height={100}
/>
Omit `elevated` or set it to `false` to restore the standard appearance. Elevated buttons support the same tooltips, loading states, links, and keyboard interactions.
<StoryEmbed
title="Elevated icon action with tooltip"
storyId="ui-components-iconbutton--elevated-tooltip"
height={140}
/>
Replace existing `FloatingIconButton` controls with `IconButton elevated`. Pass the icon as children, use native `aria-label`, and map `small` to `sm` and `medium` to `md`. Supply `size="sm"` when the previous control used its default size. Native focus and `aria-pressed` replace synthetic focus and active flags.
`FloatingIconButtonGroup` is removed. Compose ButtonGroup with IconButton for grouped actions, and keep any shared floating surface in your layout.
## Grouped actions
```tsx
import { ButtonGroup } from 'twenty-ui/primitives/input';
import { IconButton } from 'twenty-ui/components/input';
import { IconPlus, IconSearch } from 'twenty-ui/icon';
export const RecordActions = () => (
<ButtonGroup
aria-label="Record actions"
size="sm"
variant="solid"
color="accent"
>
<IconButton
aria-label="Search records"
tooltip="Search records"
variant="outline"
color="neutral"
>
<IconSearch />
</IconButton>
<IconButton aria-label="Create record" tooltip="Create record">
<IconPlus />
</IconButton>
</ButtonGroup>
);
```
[ButtonGroup](/ui/primitives/input/button-group) supplies defaults for size, variant, and color, plus adjoining corners. Explicit child props take precedence independently, including `size="xs"`. Individual buttons do not need a position prop.
Keep attached buttons the same size so their edges align. Set the size on the group and let each button inherit it.
<StoryEmbed
storyId="ui-components-iconbutton--grouped-overrides"
title="Individual icon button appearance in a group"
height={140}
/>
## Links and forms
Without a custom `render`, `href` renders an anchor unless `nativeButton` is explicitly true. For a custom navigation anchor or router link, set `nativeButton={false}` and `role="link"`. The renderer can own its destination without an IconButton `href`. Keep `nativeButton` true for a custom native button, and use false for a non-native action element. Explicit nativeButton and role props are preserved. Disabled and loading links cannot activate. Routing stays in the application.
Native button and anchor attributes, event handlers, event details, refs, and render composition pass through to Button. The ref receives the actual root element. Tooltip composition preserves that root and its accessible name. The default is `type="button"`; set `type="submit"` explicitly for form submission.
## Compact and round controls
Use `size="xs"` for a 20px control and `shape="round"` for circular corners. Existing `RoundedIconButton` controls become `IconButton` with `shape="round"`, `variant="solid"`, and `color="accent"`. Map their old `small` size to `xs` and `medium` size to `sm`. Supply icon children and an accessible name.
<StoryEmbed
storyId="ui-components-iconbutton--round-documentation"
title="Round icon buttons in compact and regular sizes"
height={140}
/>
## Props
<IconButtonReference />
<PageBanner illustration="page-cover-pointer" />