Button

Buttons let users perform actions instantly, such as submitting forms, navigating pages, or triggering app functions. Built with comprehensive state management and semantic color coding, they communicate purpose and priority while maintaining consistent behavior across desktop and mobile environments.

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

Examples

Variants

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

Fill
Outline
Ghost
<Button emphasis="primary" startIcon={ExternalLink} variant="fill">
  Action
</Button>
<Button emphasis="primary" startIcon={ExternalLink} variant="outline">
  Action
</Button>
<Button emphasis="primary" startIcon={ExternalLink} variant="ghost">
  Action
</Button>

Emphasis

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

Neutral
Primary
Danger
<Button emphasis="neutral" startIcon={ExternalLink} variant="fill">
  Action
</Button>
<Button emphasis="primary" startIcon={ExternalLink} variant="fill">
  Action
</Button>
<Button emphasis="danger" startIcon={ExternalLink} variant="fill">
  Action
</Button>

Sizes and Icons

Control dimensions with the size prop. Icons are supplied using the startIcon and endIcon props.

<Button
  emphasis="primary"
  size="sm"
  startIcon={ExternalLink}
  variant="fill"
>
  Action
</Button>
<Button
  emphasis="primary"
  size="md"
  startIcon={ExternalLink}
  variant="fill"
>
  Action
</Button>
<Button
  emphasis="primary"
  size="lg"
  startIcon={ExternalLink}
  variant="fill"
>
  Action
</Button>

Compact Density

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

<Button
  density="compact"
  emphasis="primary"
  size="sm"
  startIcon={ExternalLink}
  variant="fill"
>
  Action
</Button>
<Button
  density="compact"
  emphasis="primary"
  size="md"
  startIcon={ExternalLink}
  variant="fill"
>
  Action
</Button>
<Button
  density="compact"
  emphasis="primary"
  size="lg"
  startIcon={ExternalLink}
  variant="fill"
>
  Action
</Button>

Variant Combinations

This grid shows all button combinations across variants and emphasis levels. The bottom row demonstrates the disabled state, which grays out the button regardless of variant or emphasis.

FillOutlineGhost
<Button emphasis="neutral" variant="fill">
  Action
</Button>
<Button emphasis="neutral" variant="outline">
  Action
</Button>
<Button emphasis="neutral" variant="ghost">
  Action
</Button>

<Button emphasis="primary" variant="fill">
  Action
</Button>
<Button emphasis="primary" variant="outline">
  Action
</Button>
<Button emphasis="primary" variant="ghost">
  Action
</Button>

<Button emphasis="danger" variant="fill">
  Action
</Button>
<Button emphasis="danger" variant="outline">
  Action
</Button>
<Button emphasis="danger" variant="ghost">
  Action
</Button>

<Button disabled variant="fill">
  Action
</Button>
<Button disabled variant="outline">
  Action
</Button>
<Button disabled variant="ghost">
  Action
</Button>

Contrast Colors

Use persistent-white for buttons on dark backgrounds and persistent-black for buttons on light backgrounds. These emphasis values maintain consistent contrast regardless of the active theme.

<div className="bg-persistent-black flex gap-8 rounded-md p-3">
  <Button emphasis="persistent-white" variant="fill">
    Action
  </Button>
  <Button emphasis="persistent-white" variant="outline">
    Action
  </Button>
  <Button emphasis="persistent-white" variant="ghost">
    Action
  </Button>
</div>

<div className="bg-persistent-white flex gap-8 rounded-md p-3">
  <Button emphasis="persistent-black" variant="fill">
    Action
  </Button>
  <Button emphasis="persistent-black" variant="outline">
    Action
  </Button>
  <Button emphasis="persistent-black" variant="ghost">
    Action
  </Button>
</div>

Inverse Contrast

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

<Button emphasis="inverse" variant="fill">
  Action
</Button>
<Button emphasis="inverse" variant="outline">
  Action
</Button>
<Button emphasis="inverse" variant="ghost">
  Action
</Button>

Badge

Supply a NumberBadge or StatusBadge with the badge prop. The badge renders after the label and before the end icon.

The button passes these defaults to its badge:

  • A disabled button disables its badge.
  • Badge size follows the button size.
  • NumberBadge emphasis follows the button's variant and emphasis.
  • StatusBadge emphasis is not changed.

Props set on the badge take precedence over these defaults.

Button sizeNumberBadge sizeStatusBadge size
smxssm
mdxssm
lgsmmd
Button emphasisNumberBadge emphasis on fillNumberBadge emphasis on outline and ghost
neutralpersistent-whiteneutral
primarypersistent-whitebrand
dangerpersistent-whitedanger
persistent-whitepersistent-whitepersistent-white
persistent-blackpersistent-blackpersistent-black
inverseneutralneutral

The badge prop is also available on Menu.Button, and on Menu.SplitButton through actionProps.badge.

<Button
  badge={<NumberBadge value={3} />}
  emphasis="primary"
  startIcon={Mail}
  variant="fill"
>
  Inbox
</Button>
<Button
  badge={<NumberBadge value={120} />}
  emphasis="primary"
  variant="outline"
>
  Notifications
</Button>
<Button badge={<StatusBadge emphasis="success" />} variant="outline">
  Online
</Button>

For a button that opens a dropdown, use Menu.Button for a labeled trigger or Menu.IconButton for an icon-only trigger.

Split Button

For a button that pairs a primary action with a dropdown of related actions, use Menu.SplitButton.

API

<Button>

A styled button. Renders a <button> element by default.
PropTypeDefault
v1.32.0
A NumberBadge or StatusBadge, positioned after the text content. Its emphasis, size, and disabled state default to values that match the button. Props set on the badge take precedence.
The density of the button. Governs padding and height.
| 'default'
| 'compact'
'default'
Controls whether the component is interactive. When true, pointer/focus events are blocked, and the component is visually dimmed.
boolean
false
The style variant of the button. Governs colors.
| 'neutral'
| 'primary'
| 'danger'
| 'persistent-white'
| 'persistent-black'
| 'inverse'
| 'white-persistent'
| 'black-persistent'
'neutral'
Icon positioned after the text content. If supplied as a LucideIcon, the size will automatically match the size prop. Supply as a ReactElement for additional customization.
| LucideIcon
| ReactElement
| null
Allows you to replace the component's HTML element with a different tag or component. Learn more
| ReactElement
| ((
props: object,
) => ReactElement)
The size of the component and its icons.
| 'sm'
| 'md'
| 'lg'
'md'
Icon positioned before the text content. If supplied as a LucideIcon, the size will automatically match the size prop. Supply as a ReactElement for additional customization.
| LucideIcon
| ReactElement
| null
The style variant of the button. Governs colors.
| 'fill'
| 'ghost'
| 'outline'
'fill'
v1.32.0
Description
A NumberBadge or StatusBadge, positioned after the text content. Its emphasis, size, and disabled state default to values that match the button. Props set on the badge take precedence.
Type
| 'default'
| 'compact'
Description
The density of the button. Governs padding and height.
Type
boolean
Description
Controls whether the component is interactive. When true, pointer/focus events are blocked, and the component is visually dimmed.
Type
| 'neutral'
| 'primary'
| 'danger'
| 'persistent-white'
| 'persistent-black'
| 'inverse'
| 'white-persistent'
| 'black-persistent'
Description
The style variant of the button. Governs colors.
Type
| LucideIcon
| ReactElement
| null
Description
Icon positioned after the text content. If supplied as a LucideIcon, the size will automatically match the size prop. Supply as a ReactElement for additional customization.
Type
| ReactElement
| ((
props: object,
) => ReactElement)
Description
Allows you to replace the component's HTML element with a different tag or component. Learn more
Type
| 'sm'
| 'md'
| 'lg'
Description
The size of the component and its icons.
Type
| LucideIcon
| ReactElement
| null
Description
Icon positioned before the text content. If supplied as a LucideIcon, the size will automatically match the size prop. Supply as a ReactElement for additional customization.
Type
| 'fill'
| 'ghost'
| 'outline'
Description
The style variant of the button. Governs colors.

Start Icon

Provided via the startIcon prop.

End Icon

Provided via the endIcon prop.

Updated by Ryan Bower