SegmentButton

Beta

Segmented control for single or multiple option selection.

Installation

npm install @xaui/native

Import

import { SegmentButton, SegmentButtonItem } from '@xaui/native/segment-button'

Basic Usage

Minimal example showing the component with its default configuration.

import { SegmentButton } from '@xaui/native/segment-button'

export function Example() {
  return <SegmentButton />
}

Single Selection (Controlled)

Control the selected segment with string state.

import { useState } from 'react'
import { SegmentButton, SegmentButtonItem } from '@xaui/native/segment-button'
import { Typography } from '@xaui/native/typography'

export function SingleControlledSegmentButtonExample() {
  const [value, setValue] = useState('week')

  return (
    <>
      <SegmentButton
        selected={value}
        onSelectionChange={next => setValue(next as string)}
        fullWidth
      >
        <SegmentButtonItem itemKey="day" label="Day" />
        <SegmentButtonItem itemKey="week" label="Week" />
        <SegmentButtonItem itemKey="month" label="Month" />
      </SegmentButton>
      <Typography variant="caption">Selected: {value}</Typography>
    </>
  )
}

Multiple Selection

Use selectionMode="multiple" with string[] state.

import { useState } from 'react'
import { SegmentButton, SegmentButtonItem } from '@xaui/native/segment-button'

export function MultiSelectSegmentButtonExample() {
  const [keys, setKeys] = useState<string[]>(['new', 'popular'])

  return (
    <SegmentButton
      selectionMode="multiple"
      selected={keys}
      onSelectionChange={next => setKeys(next as string[])}
      variant="flat"
      fullWidth
    >
      <SegmentButtonItem itemKey="new" label="New" />
      <SegmentButtonItem itemKey="popular" label="Popular" />
      <SegmentButtonItem itemKey="sale" label="Sale" />
    </SegmentButton>
  )
}

Variants and Elevation

Compare visual variants and use elevation where supported.

import { SegmentButton, SegmentButtonItem } from '@xaui/native/segment-button'
import { Column } from '@xaui/native/view'

export function SegmentButtonVariantsExample() {
  return (
    <Column gap={10}>
      <SegmentButton defaultSelected="a" variant="outlined" fullWidth>
        <SegmentButtonItem itemKey="a" label="One" />
        <SegmentButtonItem itemKey="b" label="Two" />
      </SegmentButton>
      <SegmentButton defaultSelected="a" variant="light" fullWidth>
        <SegmentButtonItem itemKey="a" label="One" />
        <SegmentButtonItem itemKey="b" label="Two" />
      </SegmentButton>
      <SegmentButton defaultSelected="a" variant="flat" elevation={2} fullWidth>
        <SegmentButtonItem itemKey="a" label="One" />
        <SegmentButtonItem itemKey="b" label="Two" />
      </SegmentButton>
      <SegmentButton defaultSelected="a" variant="faded" elevation={1} fullWidth>
        <SegmentButtonItem itemKey="a" label="One" />
        <SegmentButtonItem itemKey="b" label="Two" />
      </SegmentButton>
    </Column>
  )
}

Size and Theme Color

Tune density and semantic color.

import { SegmentButton, SegmentButtonItem } from '@xaui/native/segment-button'
import { Column } from '@xaui/native/view'

export function SegmentButtonSizeThemeExample() {
  return (
    <Column gap={10}>
      <SegmentButton defaultSelected="std" size="xs" themeColor="primary" fullWidth>
        <SegmentButtonItem itemKey="std" label="Standard" />
        <SegmentButtonItem itemKey="exp" label="Express" />
      </SegmentButton>
      <SegmentButton defaultSelected="std" size="md" themeColor="secondary" fullWidth>
        <SegmentButtonItem itemKey="std" label="Standard" />
        <SegmentButtonItem itemKey="exp" label="Express" />
      </SegmentButton>
      <SegmentButton defaultSelected="std" size="lg" themeColor="success" fullWidth>
        <SegmentButtonItem itemKey="std" label="Standard" />
        <SegmentButtonItem itemKey="exp" label="Express" />
      </SegmentButton>
    </Column>
  )
}

States and Custom Content

Disable segments, hide checkmarks, and attach start/end content.

import { SegmentButton, SegmentButtonItem } from '@xaui/native/segment-button'
import { Typography } from '@xaui/native/typography'

export function SegmentButtonStatesExample() {
  return (
    <SegmentButton
      defaultSelected="home"
      showCheckmark={false}
      radius="md"
      fullWidth
    >
      <SegmentButtonItem
        itemKey="home"
        label="Home"
        startContent={<Typography>🏠</Typography>}
      />
      <SegmentButtonItem
        itemKey="search"
        label="Search"
        startContent={<Typography>🔎</Typography>}
      />
      <SegmentButtonItem
        itemKey="profile"
        label="Profile"
        endContent={<Typography>•</Typography>}
        isDisabled
      />
    </SegmentButton>
  )
}