> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# IconButton
> Trigger actions with accessible icon buttons.
export const StoryEmbed = ({storyId, title, height = 120}) => <>
Open in Storybook
;
`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.
## Usage
```tsx theme={null}
import { IconButton } from 'twenty-ui/components/input';
import { IconSearch } from 'twenty-ui/icon';
export const SearchButton = () => (
);
```
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.
## 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 theme={null}
import { IconButton } from 'twenty-ui/components/input';
import { IconSearch } from 'twenty-ui/icon';
import { Text } from 'twenty-ui/primitives/typography';
export const LabelledSearchButton = () => (
} id="records-search-label">
Search records
);
```
## 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 theme={null}
import { IconButton } from 'twenty-ui/components/input';
import { IconSearch } from 'twenty-ui/icon';
export const SearchRecordsButton = () => (
);
```
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 theme={null}
import { IconButton } from 'twenty-ui/components/input';
import { IconPlus } from 'twenty-ui/icon';
export const AddWidgetButton = () => (
);
```
Omit `elevated` or set it to `false` to restore the standard appearance. Elevated buttons support the same tooltips, loading states, links, and keyboard interactions.
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 theme={null}
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](/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.
## 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.
## Props
Accessible name describing the action. Required unless `aria-labelledby` supplies the name.
ID of the element supplying the accessible name. Can be used instead of `aria-label`.
Icon content. Decorative and hidden from assistive technology.
CSS class applied to the element, or a function that
returns a class based on the component's state.
Semantic color of the button.
Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors.
Whether the button should be focusable when disabled.
Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract.
Shows a loading indicator and disables activation.
Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence.
Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role="link"` for a custom navigation anchor. Router integration belongs to the caller.
Role of the root element. Use `link` for custom navigation renderers.
Square or round icon control.
Button size: `xs` (20px), `sm` (24px), or `md` (32px).
Style applied to the element, or a function that
returns a style object based on the component's state.
Text displayed when hovering or focusing the button.
Delay before showing the tooltip.
Distance in pixels between the button and the tooltip.
Preferred placement of the tooltip relative to the button.
Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.