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 white-persistent for buttons on dark backgrounds and black-persistent 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="white-persistent" variant="fill">
    Action
  </Button>
  <Button emphasis="white-persistent" variant="outline">
    Action
  </Button>
  <Button emphasis="white-persistent" variant="ghost">
    Action
  </Button>
</div>

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

API

<Button>

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

Prop	Type	Default
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'	'neutral'
endIcon 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 \| ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
size The size of the component and its icons.	\| 'sm' \| 'md' \| 'lg'	'md'
startIcon 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 \| ReactNode
variant The style variant of the button. Governs colors.	\| 'fill' \| 'ghost' \| 'outline'	'fill'

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'

Description

The style variant of the button. Governs colors.

endIcon

Type

| LucideIcon
| ReactNode

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.

render

Type

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

Description

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

size

Type

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

Description

The size of the component and its icons.

startIcon

Type

| LucideIcon
| ReactNode

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.

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-kind`	'text'
`data-part`	'root'
`data-scope`	'button'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-variant`	\| 'fill' \| 'ghost' \| 'outline'

className

Value

'qui-button__root'

data-density

Value

| 'default'
| 'compact'

data-disabled

Value

data-kind

Value

'text'

data-part

Value

'root'

data-scope

Value

'button'

data-size

Value

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

data-variant

Value

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

Start Icon

Provided via the startIcon prop.

Attribute / Property	Value
`className`	'qui-button__icon'
`data-density`	\| 'default' \| 'compact'
`data-part`	'icon'
`data-placement`	'start'
`data-scope`	'button'
`data-size`	\| 'sm' \| 'md' \| 'lg'

className

Value

'qui-button__icon'

data-density

Value

| 'default'
| 'compact'

data-part

Value

'icon'

data-placement

Value

'start'

data-scope

Value

'button'

data-size

Value

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

End Icon

Provided via the endIcon prop.

Attribute / Property	Value
`className`	'qui-button__icon'
`data-density`	\| 'default' \| 'compact'
`data-part`	'icon'
`data-placement`	'end'
`data-scope`	'button'
`data-size`	\| 'sm' \| 'md' \| 'lg'

className

Value

'qui-button__icon'

data-density

Value

| 'default'
| 'compact'

data-part

Value

'icon'

data-placement

Value

'end'

data-scope

Value

'button'

data-size

Value

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

Overview

Button Group