Ark Logo

Segment Group

Organizes and navigates between sections in a view.

Anatomy

To set up the segmented control correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the SegmentGroup component in your project. Let's take a look at the most basic example:

import { SegmentGroup } from '@ark-ui/react'

export const Basic = () => {
  const frameworks = ['React', 'Solid', 'Svelte', 'Vue']
  return (
    <SegmentGroup.Root>
      <SegmentGroup.Indicator />
      {frameworks.map((framework) => (
        <SegmentGroup.Item key={framework} value={framework}>
          <SegmentGroup.ItemText>{framework}</SegmentGroup.ItemText>
          <SegmentGroup.ItemControl />
        </SegmentGroup.Item>
      ))}
    </SegmentGroup.Root>
  )
}

Initial Value

To set a default segment on initial render, use the defaultValue prop:

Example not found

Controlled Segment Group

To create a controlled SegmentGroup component, manage the current selected segment using the value prop and update it when the onValueChange event handler is called:

import { useState } from 'react'
import { SegmentGroup } from '@ark-ui/react'

export const Controlled = () => {
  const frameworks = ['React', 'Solid', 'Svelte', 'Vue']
  const [value, setValue] = useState('React')
  return (
    <SegmentGroup.Root value={value} onValueChange={(e) => setValue(e.value)}>
      <SegmentGroup.Indicator />
      {frameworks.map((framework) => (
        <SegmentGroup.Item key={framework} value={framework}>
          <SegmentGroup.ItemText>{framework}</SegmentGroup.ItemText>
          <SegmentGroup.ItemControl />
        </SegmentGroup.Item>
      ))}
    </SegmentGroup.Root>
  )
}

Disabled Segment

To disable a segment, simply pass the disabled prop to the SegmentGroup.Item component:

import { SegmentGroup } from '@ark-ui/react'

export const Disabled = () => {
  const frameworks = ['React', 'Solid', 'Svelte', 'Vue']
  return (
    <SegmentGroup.Root defaultValue="React">
      <SegmentGroup.Indicator />
      {frameworks.map((framework) => (
        <SegmentGroup.Item key={framework} value={framework} disabled={framework === 'Svelte'}>
          <SegmentGroup.ItemText>{framework}</SegmentGroup.ItemText>
          <SegmentGroup.ItemControl />
        </SegmentGroup.Item>
      ))}
    </SegmentGroup.Root>
  )
}

API Reference

Root

PropDefaultType
asChild
boolean

Render as a different element type.

defaultValue
string

The initial value of the segment group when it is first rendered. Use when you do not need to control the state of the segment group.

disabled
boolean

If `true`, the radio group will be disabled

form
string

The associate form of the underlying input.

id
string

The unique identifier of the machine.

ids
Partial<{ root: string label: string indicator: string item(value: string): string itemLabel(value: string): string itemControl(value: string): string itemHiddenInput(value: string): string }>

The ids of the elements in the radio. Useful for composition.

name
string

The name of the input fields in the radio (Useful for form submission).

onValueChange
(details: ValueChangeDetails) => void

Function called once a radio is checked

orientation
'horizontal' | 'vertical'

Orientation of the radio group

readOnly
boolean

Whether the checkbox is read-only

value
string

The value of the checked radio

Indicator

PropDefaultType
asChild
boolean

Render as a different element type.

ItemControl

PropDefaultType
asChild
boolean

Render as a different element type.

Item

PropDefaultType
value
string

asChild
boolean

Render as a different element type.

disabled
boolean

invalid
boolean

ItemText

PropDefaultType
asChild
boolean

Render as a different element type.

Label

PropDefaultType
asChild
boolean

Render as a different element type.