Segmented

A cross-platform React segmented control component for switching between related views or filters. Similar to iOS's UISegmentedControl.

Segmented is a control that lets users choose one option from a small set of mutually exclusive choices, all shown side by side. It's commonly used to switch between views, modes, or filters, with the selected segment visually highlighted.

When to use

• To switch between a few mutually exclusive views, modes, or filters
• When all options should stay visible and easy to compare
• For a small set of options (2–7) with short labels

When not to use

• For many options or long labels — use a Select or Tabs instead
• When more than one option can be active — use a group of toggles or checkboxes
• To trigger actions rather than switch state — use Buttons
• For a simple on/off — use a Switch

Content guidelines

Keep labels short and parallel in structure — one or two words each.

Keep the number of segments small (the example tops out around 7) so they all fit without crowding.

Always keep exactly one segment selected.

Use similar label lengths so segment widths stay balanced.

Behaviour guidelines

Exactly one segment is selected at a time; choosing one deselects the rest.

Item Count sets how many segments appear; they share the control's width evenly or size to their content.

Selecting a segment switches the related view or state immediately.

Avoid overflow — if the options no longer fit, switch to a Select or Tabs.

Accessibility

Expose it as a single-select group and mark the selected segment programmatically (e.g. aria-checked / aria-selected).

Support keyboard operation: move between segments with the arrow keys and select with Enter or Space.

Never communicate the selected state through color alone — keep a clear, non-color indicator.

Show a visible focus indicator on the focused segment.

Installation

npm install @xsolla/xui-segmented

Demo

Basic Segmented

import * as React from "react";
import { Segmented } from "@xsolla/xui-segmented";

export default function BasicSegmented() {
  const [active, setActive] = React.useState("day");

  return (
    <Segmented
      items={[
        { id: "day", label: "Day" },
        { id: "week", label: "Week" },
        { id: "month", label: "Month" },
      ]}
      activeId={active}
      onChange={setActive}
    />
  );
}

With Icons

import * as React from "react";
import { Segmented } from "@xsolla/xui-segmented";
import { Grid, List } from "@xsolla/xui-icons-base";

export default function IconSegmented() {
  const [active, setActive] = React.useState("grid");

  return (
    <Segmented
      items={[
        { id: "grid", label: "Grid", icon: <Grid size={16} /> },
        { id: "list", label: "List", icon: <List size={16} /> },
      ]}
      activeId={active}
      onChange={setActive}
    />
  );
}

Full Width

import * as React from "react";
import { Segmented } from "@xsolla/xui-segmented";

export default function FullWidthSegmented() {
  const [active, setActive] = React.useState("all");

  return (
    <div style={{ width: 400 }}>
      <Segmented
        fullWidth={true}
        items={[
          { id: "all", label: "All" },
          { id: "active", label: "Active" },
          { id: "completed", label: "Completed" },
        ]}
        activeId={active}
        onChange={setActive}
      />
    </div>
  );
}

Anatomy

import { Segmented } from "@xsolla/xui-segmented";

<Segmented
  items={[
    // Array of segment items
    { id: "a", label: "A" },
    { id: "b", label: "B" },
  ]}
  activeId="a" // Currently active item ID
  onChange={handleChange} // Selection change handler
  size="md" // Size variant
  fullWidth={false} // Expand to container width
/>;

Examples

Segmented Sizes

import * as React from "react";
import { Segmented } from "@xsolla/xui-segmented";

export default function SegmentedSizes() {
  const items = [
    { id: "a", label: "Option A" },
    { id: "b", label: "Option B" },
    { id: "c", label: "Option C" },
  ];

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
      <Segmented size="sm" items={items} activeId="a" />
      <Segmented size="md" items={items} activeId="a" />
      <Segmented size="lg" items={items} activeId="a" />
      <Segmented size="xl" items={items} activeId="a" />
    </div>
  );
}

With Disabled Items

import * as React from "react";
import { Segmented } from "@xsolla/xui-segmented";

export default function DisabledItemSegmented() {
  const [active, setActive] = React.useState("enabled1");

  return (
    <Segmented
      items={[
        { id: "enabled1", label: "Enabled" },
        { id: "disabled", label: "Disabled", disabled: true },
        { id: "enabled2", label: "Enabled" },
      ]}
      activeId={active}
      onChange={setActive}
    />
  );
}

API Reference

Segmented

Segmented Props:

| Prop | Type | Default | Description | | :-------- | :----------------------------- | :------ | :------------------------------------------------------------------------------------------------------------ | | testID | string | — | Test ID for testing frameworks. On web this renders as data-testid; on React Native it renders as testID. | | items | SegmentedItemType[] | - | Required. Array of segment items. | | activeId | string | - | ID of the currently active item. | | onChange | (id: string) => void | - | Selection change handler. | | size | "xl" \| "lg" \| "md" \| "sm" | "md" | Size variant. | | fullWidth | boolean | false | Expand segments to fill container width. | | id | string | - | HTML id attribute. | | testID | string | - | Test identifier. |

SegmentedItemType:

interface SegmentedItemType {
  id: string; // Unique identifier
  label: string; // Display text
  icon?: ReactNode; // Optional icon
  disabled?: boolean; // Disabled state
  "aria-label"?: string; // Accessible label
}

Keyboard Navigation

| Key | Action | | :--------------- | :-------------------- | | Arrow Right/Down | Move to next item | | Arrow Left/Up | Move to previous item | | Enter/Space | Select focused item |

Behavior

• Active segment has elevated background with smooth sliding animation
• Disabled segments show reduced opacity
• Keyboard navigation wraps around
• Hover effect on non-active segments

Accessibility

• Uses role="radiogroup" on container
• Each segment has role="radio"
• aria-checked indicates selection state
• aria-disabled for disabled items
• Roving tabindex for keyboard navigation