Icon Button

Icon buttons perform an action when clicked and visually represent the action through an icon, combining button functionality with visual symbolism.

import {IconButton} from "@qualcomm-ui/react/button"

Accessibility Guidelines

Icon-only buttons rely on visual cues that screen readers cannot access. Use aria-label or aria-labelledby to give every icon-only button an accessible name so its purpose is clear to assistive technologies.

Examples

Variants

Buttons come in three variants: fill, outline, and ghost. Customize these with the variant property.

Fill

Outline

Ghost

<IconButton aria-label="Navigate" icon={ExternalLink} variant="fill" />
<IconButton aria-label="Navigate" icon={ExternalLink} variant="outline" />
<IconButton aria-label="Navigate" icon={ExternalLink} variant="ghost" />

Emphasis

Control the visual emphasis with different colors: neutral, primary, and danger. Customize these with the emphasis prop.

Neutral

Primary

Danger

<IconButton
  aria-label="Navigate"
  emphasis="neutral"
  icon={ExternalLink}
  variant="fill"
/>
<IconButton
  aria-label="Navigate"
  emphasis="primary"
  icon={ExternalLink}
  variant="fill"
/>
<IconButton
  aria-label="Navigate"
  emphasis="danger"
  icon={ExternalLink}
  variant="fill"
/>

Sizes and Icons

Customize size using the size property. QUI buttons come with built-in support for lucide-react icons.

<IconButton
  aria-label="Navigate"
  emphasis="primary"
  icon={ExternalLink}
  size="sm"
  variant="fill"
/>
<IconButton
  aria-label="Navigate"
  emphasis="primary"
  icon={ExternalLink}
  size="md"
  variant="fill"
/>
<IconButton
  aria-label="Navigate"
  emphasis="primary"
  icon={ExternalLink}
  size="lg"
  variant="fill"
/>

Compact Density

Use the density prop to reduce the padding and height of the button. The options are default and compact.

<IconButton
  aria-label="Navigate"
  density="compact"
  emphasis="primary"
  icon={ExternalLink}
  size="sm"
  variant="fill"
/>
<IconButton
  aria-label="Navigate"
  density="compact"
  emphasis="primary"
  icon={ExternalLink}
  size="md"
  variant="fill"
/>
<IconButton
  aria-label="Navigate"
  density="compact"
  emphasis="primary"
  icon={ExternalLink}
  size="lg"
  variant="fill"
/>

Variant Combinations

This demo displays all combinations of variants and emphasis options, including the disabled state for each variant.

FillOutlineGhost

<IconButton
  aria-label="Search"
  emphasis="neutral"
  icon={Search}
  variant="fill"
/>
<IconButton
  aria-label="Search"
  emphasis="neutral"
  icon={Search}
  variant="outline"
/>
<IconButton
  aria-label="Search"
  emphasis="neutral"
  icon={Search}
  variant="ghost"
/>

Shape

Control the shape of the icon button with the shape prop. The default shape is square.

<IconButton aria-label="Navigate" icon={ExternalLink} shape="square" />
<IconButton aria-label="Navigate" icon={ExternalLink} shape="rounded" />

Contrast Colors

Use white-persistent emphasis on dark backgrounds and black-persistent emphasis on light backgrounds. These colors remain constant regardless of the active theme.

<div className="bg-persistent-black flex gap-6 p-4">
  <IconButton
    aria-label="Navigate"
    emphasis="white-persistent"
    icon={ExternalLink}
    variant="fill"
  />
  <IconButton
    aria-label="Navigate"
    emphasis="white-persistent"
    icon={ExternalLink}
    variant="outline"
  />
  <IconButton
    aria-label="Navigate"
    emphasis="white-persistent"
    icon={ExternalLink}
    variant="ghost"
  />
</div>

Inverse Contrast

To flip contrast against the active theme, set emphasis to inverse.

<IconButton
  aria-label="Navigate"
  emphasis="inverse"
  icon={ExternalLink}
  variant="fill"
/>
<IconButton
  aria-label="Navigate"
  emphasis="inverse"
  icon={ExternalLink}
  variant="outline"
/>
<IconButton
  aria-label="Navigate"
  emphasis="inverse"
  icon={ExternalLink}
  variant="ghost"
/>

API

<IconButton>

A styled icon button. Renders a <button> element by default.

Prop	Type	Default
icon ^* lucide-react icon. Can be supplied as a `ReactElement` for additional customization.	\| LucideIcon \| ReactNode
density The density of the button. Governs padding and height.	\| 'default' \| 'compact'	'default'
disabled Controls whether the component is interactive. When `true`, pointer/focus events are blocked, and the component is visually dimmed.	boolean	false
emphasis The style variant of the button. Governs colors.	\| 'neutral' \| 'primary' \| 'danger' \| 'white-persistent' \| 'black-persistent' \| 'inverse'	'neutral'
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
shape Governs the shape of the icon button.	\| 'square' \| 'rounded'	'square'
size The size of the component and its icons.	\| 'sm' \| 'md' \| 'lg'	'md'
variant The style variant of the button. Governs colors.	\| 'fill' \| 'ghost' \| 'outline'	'fill'

icon

Type

| LucideIcon
| ReactNode

Description

lucide-react icon. Can be supplied as a ReactElement for additional customization.

density

Type

| 'default'
| 'compact'

Description

The density of the button. Governs padding and height.

disabled

Type

boolean

Description

Controls whether the component is interactive. When true, pointer/focus events are blocked, and the component is visually dimmed.

emphasis

Type

| 'neutral'
| 'primary'
| 'danger'
| 'white-persistent'
| 'black-persistent'
| 'inverse'

Description

The style variant of the button. Governs colors.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

shape

Type

| 'square'
| 'rounded'

Description

Governs the shape of the icon button.

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the component and its icons.

variant

Type

| 'fill'
| 'ghost'
| 'outline'

Description

The style variant of the button. Governs colors.

Attribute / Property	Value
`className`	'qui-button__root'
`data-density`	\| 'default' \| 'compact'
`data-disabled`
`data-icon-button-part`	'root'
`data-shape`	\| 'square' \| 'rounded'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-variant`	\| 'fill' \| 'ghost' \| 'outline'

className

Value

'qui-button__root'

data-density

Value

| 'default'
| 'compact'

data-disabled

Value

data-icon-button-part

Value

'root'

data-shape

Value

| 'square'
| 'rounded'

data-size

Value

| 'sm'
| 'md'
| 'lg'

data-variant

Value

| 'fill'
| 'ghost'
| 'outline'

Last updated on May 23, 2026 by Ryan Bower

Icon

Inline Icon Button