Components
Segment group

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:

<script setup lang="ts">
import { SegmentGroup } from '@ark-ui/vue/segment-group'
import { ref } from 'vue'

const frameworks = ref(['React', 'Solid', 'Svelte', 'Vue'])
</script>

<template>
  <SegmentGroup.Root>
    <SegmentGroup.Indicator />
    <SegmentGroup.Item v-for="framework in frameworks" :key="framework" :value="framework">
      <SegmentGroup.ItemText>{{ framework }}</SegmentGroup.ItemText>
      <SegmentGroup.ItemControl />
      <SegmentGroup.ItemHiddenInput />
    </SegmentGroup.Item>
  </SegmentGroup.Root>
</template>

Initial Value

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

<script setup lang="ts">
import { SegmentGroup } from '@ark-ui/vue/segment-group'
import { ref } from 'vue'

const frameworks = ref(['React', 'Solid', 'Svelte', 'Vue'])
</script>

<template>
  <SegmentGroup.Root model-value="React">
    <SegmentGroup.Indicator />
    <SegmentGroup.Item v-for="framework in frameworks" :key="framework" :value="framework">
      <SegmentGroup.ItemText>{{ framework }}</SegmentGroup.ItemText>
      <SegmentGroup.ItemControl />
      <SegmentGroup.ItemHiddenInput />
    </SegmentGroup.Item>
  </SegmentGroup.Root>
</template>

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:

<script setup lang="ts">
import { SegmentGroup } from '@ark-ui/vue/segment-group'
import { ref } from 'vue'

const frameworks = ref(['React', 'Solid', 'Svelte', 'Vue'])
const value = ref('React')
</script>

<template>
  <SegmentGroup.Root v-model="value">
    <SegmentGroup.Indicator />
    <SegmentGroup.Item v-for="framework in frameworks" :key="framework" :value="framework">
      <SegmentGroup.ItemText>{{ framework }}</SegmentGroup.ItemText>
      <SegmentGroup.ItemControl />
      <SegmentGroup.ItemHiddenInput />
    </SegmentGroup.Item>
  </SegmentGroup.Root>
</template>

Disabled Segment

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

<script setup lang="ts">
import { SegmentGroup } from '@ark-ui/vue/segment-group'
import { ref } from 'vue'

const frameworks = ref(['React', 'Solid', 'Svelte', 'Vue'])
</script>

<template>
  <SegmentGroup.Root model-value="React">
    <SegmentGroup.Indicator />
    <SegmentGroup.Item
      v-for="framework in frameworks"
      :key="framework"
      :value="framework"
      :disabled="framework === 'Svelte'"
    >
      <SegmentGroup.ItemText>{{ framework }}</SegmentGroup.ItemText>
      <SegmentGroup.ItemControl />
      <SegmentGroup.ItemHiddenInput />
    </SegmentGroup.Item>
  </SegmentGroup.Root>
</template>

Using the Root Provider

The RootProvider component provides a context for the radio-group. It accepts the value of the useRadio-group hook. You can leverage it to access the component state and methods from outside the radio-group.

<script setup lang="ts">
import { SegmentGroup, useSegmentGroup } from '@ark-ui/vue/segment-group'
import { ref } from 'vue'

const frameworks = ref(['React', 'Solid', 'Svelte', 'Vue'])

const segmentGroup = useSegmentGroup()
</script>

<template>
  <button @click="segmentGroup.focus()">Focus</button>

  <SegmentGroup.RootProvider :value="segmentGroup">
    <SegmentGroup.Indicator />
    <SegmentGroup.Item v-for="framework in frameworks" :key="framework" :value="framework">
      <SegmentGroup.ItemText>{{ framework }}</SegmentGroup.ItemText>
      <SegmentGroup.ItemControl />
      <SegmentGroup.ItemHiddenInput />
    </SegmentGroup.Item>
  </SegmentGroup.RootProvider>
</template>

If you're using the RootProvider component, you don't need to use the Root component.

API Reference

Root

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
defaultValue
string

The initial value of the radio group when it is first rendered. Use when you do not need to control the state of the radio 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.

modelValue
string

name
string

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

orientation
'horizontal' | 'vertical'

Orientation of the radio group

readOnly
boolean

Whether the checkbox is read-only

EmitEvent
update:modelValue
[value: string]

The callback fired when the model value changes.

valueChange
[details: ValueChangeDetails]

Function called once a radio is checked

Data AttributeValue
[data-scope]radio-group
[data-part]root
[data-orientation]The orientation of the radio-group
[data-disabled]Present when disabled

Indicator

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]radio-group
[data-part]indicator
[data-disabled]Present when disabled
[data-orientation]The orientation of the indicator

ItemControl

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]radio-group
[data-part]item-control
[data-active]Present when active or pressed

ItemHiddenInput

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Item

PropDefaultType
value
string

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
disabled
boolean

invalid
boolean

ItemText

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Label

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]radio-group
[data-part]label
[data-orientation]The orientation of the label
[data-disabled]Present when disabled

RootProvider

PropDefaultType
value
MachineApi<PropTypes>

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Accessibility

Complies with the Radio WAI-ARIA design pattern.

Keyboard Support

KeyDescription
Tab
Moves focus to either the checked radio item or the first radio item in the group.
Space
When focus is on an unchecked radio item, checks it.
ArrowDown
Moves focus and checks the next radio item in the group.
ArrowRight
Moves focus and checks the next radio item in the group.
ArrowUp
Moves focus to the previous radio item in the group.
ArrowLeft
Moves focus to the previous radio item in the group.