Segment Group for Ark UI

One label stays selected in a short row, and nothing opens underneath.

Use it for a view switch or a filter when one option is enough. If each choice should reveal its own panel, use Tabs. In React, Ark UI slides the highlight to the selected item.

Installation

Anatomy

Usage

import {
  SegmentGroup, SegmentGroupItem, SegmentGroupItemText,
} from "@/components/ui/segment-group";

const SegmentGroupDemo = () => (
  <SegmentGroup className="rounded-lg" defaultValue="Profile">
    {items.map((item) => (
      <SegmentGroupItem className="px-2 py-1.5 text-sm" key={item} value={item}>
        <SegmentGroupItemText>{item}</SegmentGroupItemText>
      </SegmentGroupItem>
    ))}
  </SegmentGroup>
);

const items = ["Profile", "Account", "Security", "Notifications"];

The selected SegmentGroupItem carries data-checked, the same attribute on every base and framework: style it with data-checked: (data-checked:font-medium) and the other items with not-data-checked:.

Demos

Controlled

The selected label is stored as a string, starting at Profile, and passed back as value so the highlight and the state cannot drift. Each item still has its own value, and only one of them is selected. Use control when another part of the page has to read the choice, such as a heading that names the current section. defaultValue is enough when the group is the only consumer.

Custom Indicator

The indicator is already inside the group. Tint the element whose data-slot is segment-group-indicator, here with a translucent primary, and leave Security disabled so the highlight has to skip it. Style that existing indicator rather than drawing a second pill behind the items. It still tracks the group's position variables when the selection changes.

Disabled

disabled on the group turns every item off, including the one that was selected. Nothing can be chosen, and the highlight stays where it was. Use it while a choice is shown but locked, for example until a form above it is valid. For a single option that should be unavailable, disable that item and leave the rest of the group alone.

Disabled Item

Security is disabled on its own item, and the other three still work. The current value stays on Profile, because a disabled item cannot become selected. Use a per-item lock for a plan that does not include that section, or a step the person has not reached. The disabled row stays visible so the missing choice is not a mystery.

Indicator On Hover

There is no hover prop. Point value at the item under the pointer, and commit that choice on click so it sticks after the pointer leaves. The highlight therefore previews a section before it is committed. Use the pattern for a view switch where seeing the target early helps, and skip it if a stray hover should never move the selection.

Orientation Horizontal

orientation set to horizontal is the default: the items sit in one row and the indicator moves sideways. Set it anyway when a parent might pass vertical, or when you want the direction obvious next to the column version. It suits a short list that fits the width of the page. If the labels wrap or the row gets cramped, a column is the calmer layout.

Orientation Vertical

orientation set to vertical stacks the items, and the indicator moves up and down with the selection. Each row stretches to the width of the group. Use a column when the control sits in a sidebar, or when the labels are too long for a single line. Arrow keys follow the orientation, so up and down change the selection instead of left and right.

Variant Underline

variant set to underline drops the filled pill. A horizontal group draws a bottom border, and the indicator becomes a short primary bar under the selected label. Use it when the row should feel like in-page navigation rather than a boxed control, and the choices still do not open panels. Leave variant unset for the default filled highlight.

Variant Underline Orientation Vertical

The same underline treatment in a column: orientation is vertical and variant is underline, so the border sits on the side and the indicator is a short bar beside the selected row. Use it for a settings menu that should look like a list of links but still only changes a value. The filled pill would be heavy in a tall stack of labels.

FAQ

API Reference