Button Group

import {QButtonGroup} from "@qui/react"

Overview

A Button Group is a grouping of buttons whose actions are related to each other.

Examples

Showcase

Button Groups are composed of QButton or QIconButton components.

import {ReactNode} from "react"

import {Files, Image, User} from "lucide-react"

import {QButton, QButtonGroup, QIconButton} from "@qui/react"

export default function Showcase(): ReactNode {
  return (
    <div className="grid justify-items-center gap-4">
      <QButtonGroup variant="outline">
        <QButton startIcon={User}>Profile</QButton>
        <QButton startIcon={Image}>Images</QButton>
        <QButton startIcon={Files}>Files</QButton>
      </QButtonGroup>

      <QButtonGroup variant="outline">
        <QIconButton aria-label="User" icon={User} />
        <QIconButton aria-label="Images" icon={Image} />
        <QIconButton aria-label="Files" icon={Files} />
      </QButtonGroup>
    </div>
  )
}

Styles

import {ReactNode} from "react"

import {Files, Image, User} from "lucide-react"

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

export default function Styles(): ReactNode {
  return (
    <div className="grid justify-center gap-4">
      <QButtonGroup variant="ghost">
        <QButton startIcon={User}>Profile</QButton>
        <QButton startIcon={Image}>Images</QButton>
        <QButton startIcon={Files}>Files</QButton>
      </QButtonGroup>

      <QButtonGroup variant="outline">
        <QButton startIcon={User}>Profile</QButton>
        <QButton startIcon={Image}>Images</QButton>
        <QButton startIcon={Files}>Files</QButton>
      </QButtonGroup>

      <QButtonGroup variant="fill">
        <QButton startIcon={User}>Profile</QButton>
        <QButton startIcon={Image}>Images</QButton>
        <QButton startIcon={Files}>Files</QButton>
      </QButtonGroup>
    </div>
  )
}

Orientations

The orientation property controls the layout of the buttons in the group. The default is horizontal, but vertical is also available.

import {ReactNode} from "react"

import {Files, Image, User} from "lucide-react"

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

export default function Orientation(): ReactNode {
  return (
    <div className="grid justify-center">
      <QButtonGroup orientation="vertical" variant="outline">
        <QButton startIcon={User}>Profile</QButton>
        <QButton startIcon={Image}>Images</QButton>
        <QButton startIcon={Files}>Files</QButton>
      </QButtonGroup>
    </div>
  )
}

Sizes

Customize size using the size property.

import {ReactNode} from "react"

import {Files, Image, User} from "lucide-react"

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

export default function Sizes(): ReactNode {
  return (
    <div className="grid gap-4">
      <div className="flex">
        <div className="flex w-16 items-center text-primary q-font-heading-xs">
          xs
        </div>
        <QButtonGroup size="xs" variant="outline">
          <QButton startIcon={User}>Profile</QButton>
          <QButton startIcon={Image}>Images</QButton>
          <QButton startIcon={Files}>Files</QButton>
        </QButtonGroup>
      </div>

      <div className="flex">
        <div className="flex w-16 items-center text-primary q-font-heading-xs">
          s
        </div>
        <QButtonGroup size="s" variant="outline">
          <QButton startIcon={User}>Profile</QButton>
          <QButton startIcon={Image}>Images</QButton>
          <QButton startIcon={Files}>Files</QButton>
        </QButtonGroup>
      </div>

      <div className="flex">
        <div className="flex w-16 items-center text-primary q-font-heading-xs">
          m
        </div>
        <QButtonGroup size="m" variant="outline">
          <QButton startIcon={User}>Profile</QButton>
          <QButton startIcon={Image}>Images</QButton>
          <QButton startIcon={Files}>Files</QButton>
        </QButtonGroup>
      </div>
    </div>
  )
}

Selection Mode

Buttons within a group are selectable by default. To disable this behavior, set readonly to true.

By default, only one button can be selected at a time. Use the multiple property to enable multiple selection.

API

Props

Name & Description	Option(s)	Default
children ^* React children prop.	ReactNode
as The component used for the root node. It can be a React component or element.	\| ElementType \| ComponentType	'div'
className The className property of the Element interface gets and sets the value of the class attribute of the specified element.	string
color The color of this group's buttons.	\| 'inherit' \| 'neutral' \| 'primary' \| 'positive' \| 'warning' \| 'negative' \| 'contrast'	'neutral'
compact If true, the buttons in this group will render without space in-between.	boolean	true
defaultIndex The default selected indices.	number[]
disabled If true, this group's buttons are disabled.	boolean	false
index The selection state of this group's buttons. Represents the indices of selected buttons in this group.	number[]
multiple If true, the group will allow more than one button to be active at a time.	boolean	false
onIndexChange Callback fired whenever an item is selected or deselected. eventThe DOM event that triggered this change, typically a click or keypress. indexThe index being selected or deselected. selectedWhether the current item is selected as a result of this change. updatedStateThe updated state of expanded indices.	( event: SyntheticEvent, index: number, selected: boolean, updatedState: number[], ) => void
orientation The orientation of this group's buttons.	\| 'horizontal' \| 'vertical'	horizontal
readonly If true, buttons in this group are not selectable.	boolean	false
size The size of this group's buttons.	\| 'xs' \| 's' \| 'm'	'm'
style The style global attribute contains CSS styling declarations to be applied to the element.	CSSProperties
variant The style variant of this group's buttons.	\| 'fill' \| 'outline' \| 'ghost'	ghost

children

Type

ReactNode

Description

React children prop.

Type

| ElementType
| ComponentType

Default

'div'

Description

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

className

Type

string

Description

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

color

Type

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

Default

'neutral'

Description

The color of this group's buttons.

compact

Type

boolean

Default

true

Description

If true, the buttons in this group will render without space in-between.

defaultIndex

Type

number[]

Description

The default selected indices.

disabled

Type

boolean

Default

false

Description

If true, this group's buttons are disabled.

index

Type

number[]

Description

The selection state of this group's buttons. Represents the indices of selected buttons in this group.

multiple

Type

boolean

Default

false

Description

If true, the group will allow more than one button to be active at a time.

onIndexChange

Type

(
  event: SyntheticEvent,
  index: number,
  selected: boolean,
  updatedState: number[],
) => void

Description

Callback fired whenever an item is selected or deselected.

eventThe DOM event that triggered this change, typically a click or keypress.
indexThe index being selected or deselected.
selectedWhether the current item is selected as a result of this change.
updatedStateThe updated state of expanded indices.

orientation

Type

| 'horizontal'
| 'vertical'

Default

horizontal

Description

The orientation of this group's buttons.

readonly

Type

boolean

Default

false

Description

If true, buttons in this group are not selectable.

size

Type

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

Default

'm'

Description

The size of this group's buttons.

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 this group's buttons.

Button

Card