Button

Buttons allow users to perform an action or mark a selection.

import {QButton} from "@qui/react"

Examples

Style

Buttons come in three styles: fill, outline, and ghost. The ghost style is applied by default.

Fill

Outline

Ghost

import {ReactNode} from "react"

import {ExternalLink} from "lucide-react"

import {QButton} from "@qui/react"

export default function Styles(): ReactNode {
  return (
    <div className="grid grid-cols-3 grid-rows-2 gap-x-8 gap-y-1">
      <div className="text-primary q-font-heading-xs">Fill</div>
      <div className="text-primary q-font-heading-xs">Outline</div>
      <div className="text-primary q-font-heading-xs">Ghost</div>

      <QButton color="primary" startIcon={ExternalLink} variant="fill">
        Action
      </QButton>
      <QButton color="primary" startIcon={ExternalLink} variant="outline">
        Action
      </QButton>
      <QButton color="primary" startIcon={ExternalLink} variant="ghost">
        Action
      </QButton>
    </div>
  )
}

Colors

Customize the color of the button using the color input.

import {ReactNode} from "react"

import {QButton} from "@qui/react"

export default function Colors(): ReactNode {
  return (
    <div className="grid justify-center gap-4">
      <div className="grid grid-cols-2 grid-rows-3 gap-x-6 gap-y-5 sm:grid-cols-6 sm:grid-rows-1">
        <QButton variant="fill">Neutral</QButton>
        <QButton color="primary" variant="fill">
          Primary
        </QButton>
        <QButton color="positive" variant="fill">
          Positive
        </QButton>
        <QButton color="warning" variant="fill">
          Warning
        </QButton>
        <QButton color="negative" variant="fill">
          Negative
        </QButton>
        <QButton selected variant="fill">
          Selected
        </QButton>
      </div>
    </div>
  )
}

Contrast

The contrast color can be used to provide optimal contrast on alternate background colors.

Fill

Outline

Ghost

import {ReactNode} from "react"

import {ExternalLink} from "lucide-react"

import {QButton} from "@qui/react"

export default function Contrast(): ReactNode {
  return (
    <div className="grid justify-center">
      <div className="q-background-4-contrast grid grid-cols-3 grid-rows-2 gap-x-8 gap-y-1 rounded p-4">
        <div className="text-contrast-primary q-font-heading-xs">Fill</div>
        <div className="text-contrast-primary q-font-heading-xs">Outline</div>
        <div className="text-contrast-primary q-font-heading-xs">Ghost</div>

        <QButton color="contrast" startIcon={ExternalLink} variant="fill">
          Action
        </QButton>
        <QButton color="contrast" startIcon={ExternalLink} variant="outline">
          Action
        </QButton>
        <QButton color="contrast" startIcon={ExternalLink} variant="ghost">
          Action
        </QButton>
      </div>
    </div>
  )
}

All Colors

FillOutlineGhost

import {Fragment, ReactNode} from "react"

import {ExternalLink} from "lucide-react"

import {QButtonColor} from "@qui/base"
import {QButton} from "@qui/react"

const colors: QButtonColor[] = [
  "neutral",
  "primary",
  "positive",
  "warning",
  "negative",
]

export default function AllColors(): ReactNode {
  return (
    <div className="grid grid-cols-3 grid-rows-7 gap-x-8 gap-y-5">
      <span className="text-primary q-font-heading-xs">Fill</span>
      <span className="text-primary q-font-heading-xs">Outline</span>
      <span className="text-primary q-font-heading-xs">Ghost</span>

      {colors.map((color) => {
        return (
          <Fragment key={color}>
            <QButton color={color} startIcon={ExternalLink} variant="fill">
              Action
            </QButton>
            <QButton color={color} startIcon={ExternalLink} variant="outline">
              Action
            </QButton>
            <QButton color={color} startIcon={ExternalLink} variant="ghost">
              Action
            </QButton>
          </Fragment>
        )
      })}

      <QButton disabled startIcon={ExternalLink} variant="fill">
        Action
      </QButton>
      <QButton disabled startIcon={ExternalLink} variant="outline">
        Action
      </QButton>
      <QButton disabled startIcon={ExternalLink} variant="ghost">
        Action
      </QButton>
    </div>
  )
}

Icon Button

For icon-only buttons, refer to the Icon Button component.

Sizes and Icons

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

Loading Button

The startIcon and endIcon properties can help you customize the button for a variety of use cases. The following example features a simple loading button implementation.

import {ReactNode, useRef, useState} from "react"

import {QButton, QProgressCircle} from "@qui/react"

LoadingButton.displayName = "LoadingButton"

export default function LoadingButton(): ReactNode {
  const [loading, setLoading] = useState(false)
  const loadingTimeoutRef = useRef<ReturnType<typeof setTimeout>>(undefined)

  function onLoad() {
    clearTimeout(loadingTimeoutRef.current)
    setLoading(true)
    // simulate an async operation
    loadingTimeoutRef.current = setTimeout(() => {
      setLoading(false)
    }, 1500)
  }

  return (
    <div className="grid justify-center">
      <QButton
        color="primary"
        endIcon={
          loading ? (
            <QProgressCircle
              className="text-secondary"
              color="inherit"
              size="xxs"
            />
          ) : null
        }
        onClick={onLoad}
        variant="fill"
      >
        Load On Click
      </QButton>
    </div>
  )
}

API

Props

Name & Description	Option(s)	Default
as The component used for the root node. It can be a React component or element.	\| ElementType \| ComponentType	'button'
children React children prop.	ReactNode
className The className property of the Element interface gets and sets the value of the class attribute of the specified element.	string
classNames Apply additional classNames to the component's elements. Refer to the clsx documentation for examples. Related symbols: ClassValue	{ endIcon?: ClassValue root?: ClassValue startIcon?: ClassValue }
color The color variant of the button.	\| 'inherit' \| 'neutral' \| 'primary' \| 'positive' \| 'warning' \| 'negative' \| 'contrast'	'neutral'
dense If `true`, the component will render with reduced padding.	boolean	false
disabled If `true`, the component will not be interactive and will appear dimmed.	boolean	false
disableTransitions If `true`, all CSS transitions are disabled.	boolean	false
endIcon Icon; positioned after the children. If supplied as a `LucideIcon`, the size will automatically match the size prop. Supply as a `ReactElement` for additional customization.	\| LucideIcon \| ReactNode
fullWidth If `true`, the button will take up the entire width of its parent container.	boolean	false
selected If `true`, the button renders in the selected style. Note that this property takes precedence over the color and variant properties.	boolean	false
size The size of the component and its icons.	\| 'xs' \| 's' \| 'm' \| 'l'	'm'
startIcon Icon; positioned before the children. If supplied as a `LucideIcon`, the size will automatically match the size prop. Supply as a `ReactElement` for additional customization.	\| LucideIcon \| ReactNode
style The style global attribute contains CSS styling declarations to be applied to the element.	CSSProperties
variant The style variant of the button.	\| 'fill' \| 'outline' \| 'ghost'	'ghost'

Type

| ElementType
| ComponentType

Default

'button'

Description

The component used for the root node. It can be a React component or element.

children

Type

ReactNode

Description

React children prop.

className

Type

string

Description

The className property of the Element interface gets and sets the value of the class attribute of the specified element.

classNames

Type

{
  endIcon?: ClassValue
  root?: ClassValue
  startIcon?: ClassValue
}

Description

Apply additional classNames to the component's elements. Refer to the clsx documentation for examples.

Related symbols

Related symbols:

color

Type

| 'inherit'
| 'neutral'
| 'primary'
| 'positive'
| 'warning'
| 'negative'
| 'contrast'

Default

'neutral'

Description

The color variant of the button.

dense

Type

boolean

Default

false

Description

If true, the component will render with reduced padding.

disabled

Type

boolean

Default

false

Description

If true, the component will not be interactive and will appear dimmed.

disableTransitions

Type

boolean

Default

false

Description

If true, all CSS transitions are disabled.

endIcon

Type

| LucideIcon
| ReactNode

Description

Icon; positioned after the children. If supplied as a LucideIcon, the size will automatically match the size prop. Supply as a ReactElement for additional customization.

fullWidth

Type

boolean

Default

false

Description

If true, the button will take up the entire width of its parent container.

selected

Type

boolean

Default

false

Description

If true, the button renders in the selected style. Note that this property takes precedence over the color and variant properties.

size

Type

| 'xs'
| 's'
| 'm'
| 'l'

Default

'm'

Description

The size of the component and its icons.

startIcon

Type

| LucideIcon
| ReactNode

Description

Icon; positioned before the children. If supplied as a LucideIcon, the size will automatically match the size prop. Supply as a ReactElement for additional customization.

style

Type

CSSProperties

Description

The style global attribute contains CSS styling declarations to be applied to the element.

variant

Type

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

Default

'ghost'

Description

The style variant of the button.

Breadcrumbs

Button Group