Fanvue API Documentation

import { SegmentedControl } from "@fanvue/ui";
import type {
  SegmentedControlAppearance,
  SegmentedControlOption,
  SegmentedControlProps,
  SegmentedControlSize,
  SegmentedControlVariant,
} from "@fanvue/ui";

Examples

Brand

import { AIIcon, HomeIcon, SegmentedControl } from "@fanvue/ui";

const brandOptions = [
  { label: "Home", value: "home", icon: <HomeIcon size={16} aria-hidden="true" /> },
  { label: "Agent", value: "agent", icon: <AIIcon size={16} aria-hidden="true" />, ai: true },
];

<SegmentedControl
  appearance="brand"
  options={brandOptions}
  defaultValue="agent"
  aria-label="Navigation mode"
/>

Disabled

import { SegmentedControl } from "@fanvue/ui";

const twoOptions = [
  { label: "Net", value: "net" },
  { label: "Gross", value: "gross" },
];

<SegmentedControl options={twoOptions} disabled aria-label="Amount type" />

Controlled

import { useState } from "react";
import { SegmentedControl } from "@fanvue/ui";

const threeOptions = [
  { label: "Net", value: "net" },
  { label: "Gross", value: "gross" },
  { label: "Total", value: "total" },
];

function Example() {
  const [value, setValue] = useState("net");
  return (
    <div className="flex flex-col items-center gap-3">
      <SegmentedControl
        options={threeOptions}
        value={value}
        onChange={setValue}
        aria-label="Amount type"
      />
      <span className="typography-body-small-14px-regular text-content-secondary">
        Selected: {value}
      </span>
    </div>
  );
}

All Variants

import { SegmentedControl } from "@fanvue/ui";
import type { SegmentedControlSize, SegmentedControlVariant } from "@fanvue/ui";

const twoOptions = [
  { label: "Net", value: "net" },
  { label: "Gross", value: "gross" },
];

const threeOptions = [
  { label: "Net", value: "net" },
  { label: "Gross", value: "gross" },
  { label: "Total", value: "total" },
];

function Example() {
  const sizes: SegmentedControlSize[] = ["32", "40", "48"];
  const variants: SegmentedControlVariant[] = ["hug", "fill"];
  return (
    <div className="flex flex-col items-start gap-8">
      {variants.map((variant) => (
        <div key={variant} className="flex flex-col items-start gap-4">
          <span className="typography-body-default-16px-semibold text-content-primary capitalize">
            {variant}
          </span>
          {sizes.map((size) => (
            <div
              key={size}
              className="flex flex-col items-start gap-3"
              style={{ width: variant === "fill" ? 560 : "auto" }}
            >
              <span className="typography-description-12px-regular text-content-secondary">
                {size}px
              </span>
              <SegmentedControl
                size={size}
                variant={variant}
                options={twoOptions}
                aria-label={`${variant} ${size}px two options`}
              />
              <SegmentedControl
                size={size}
                variant={variant}
                options={threeOptions}
                aria-label={`${variant} ${size}px three options`}
              />
            </div>
          ))}
        </div>
      ))}
    </div>
  );
}

Collapsible

import { useState } from "react";
import { GridViewIcon, ListViewIcon, SegmentedControl } from "@fanvue/ui";

const iconOnlyOptions = [
  { label: "List view", value: "list", icon: <ListViewIcon size={16} aria-hidden="true" /> },
  { label: "Grid view", value: "grid", icon: <GridViewIcon size={16} aria-hidden="true" /> },
];

function Example() {
  const [view, setView] = useState("list");
  return (
    <div className="flex flex-col items-start gap-3">
      <span className="typography-body-small-14px-regular text-content-secondary">
        Drag the right edge to shrink the container — the control collapses to the selected icon
        and cycles on click.
      </span>
      <div
        className="resize-x overflow-auto rounded-lg border border-border-primary p-4"
        style={{ width: 260, minWidth: 72, maxWidth: 420 }}
      >
        <SegmentedControl
          appearance="plain"
          collapsible
          options={iconOnlyOptions}
          aria-label="View"
          value={view}
          onChange={setView}
        />
      </div>
      <span className="typography-body-small-14px-regular text-content-secondary">
        Selected: {view}
      </span>
    </div>
  );
}

Props

SegmentedControl

A compact selector for choosing between two or three mutually exclusive options where the choice affects the content immediately below it. Use instead of tabs when the options are more like settings or filters than navigation, such as toggling a list/grid view or a monthly/annual price. Rendered as a radiogroup with roving-tabindex keyboard navigation. Supports both controlled and uncontrolled usage. With collapsible, the icon-bearing plain/brand appearances shrink to a single cycling icon toggle when space is tight (rendered as a group containing one button).

SegmentedControlOption[]

required

The selectable segments. Designed for two or three mutually exclusive options.

"brand" | "pill" | "plain"

default:"pill"

Visual style of the control.

ReactNode

Single glyph for the collapsed toggle, replacing the selected option’s icon. Use it when the collapsed control should read as one switch affordance rather than as a preview of the current selection — the collapsed navigation rail shows a repeat glyph this way. The button still announces the selected option as its accessible name, so the current state stays available to assistive tech. Only meaningful alongside collapsible.

boolean

default:"false"

When true, the control automatically collapses to a single icon-only toggle whenever its container is too narrow to show every segment side by side, and expands again when the space returns. Collapsed, it shows collapsedIcon when given and otherwise the currently-selected option’s icon; clicking it (or pressing Enter/Space) advances to the next option, wrapping around from the last back to the first.Only supported for the icon-bearing "plain" and "brand" appearances, and every option must define an icon unless collapsedIcon is given (there is nothing to show otherwise). Ignored, with a dev-time warning, when those conditions are not met.

string

Initially selected value (uncontrolled). Defaults to the first option.

boolean

default:"false"

Whether the control is disabled.

((value: string) => void)

Callback fired when the selected value changes.

"32" | "40" | "48"

default:"32"

Height of the control in pixels.

string

Currently selected value (controlled).

"fill" | "hug"

default:"hug"

Segment layout.

Exported types

Also exported from @fanvue/ui: SegmentedControlAppearance, SegmentedControlOption, SegmentedControlProps, SegmentedControlSize, SegmentedControlVariant.

Setup: Installation · Theming

Getting Started

Actions

Forms & Inputs

Overlays & Dialogs

Navigation

Data Display

Feedback & Status

Layout

Media & Audio

Creator & Social

Charts

Icons & Flags

Utility

SegmentedControl

Examples

Brand

Disabled

Controlled

All Variants

Collapsible

Props

SegmentedControl

Exported types

​Examples

​Brand

​Disabled

​Controlled

​All Variants

​Collapsible

​Props

​SegmentedControl

​Exported types

Examples

Brand

Disabled

Controlled

All Variants

Collapsible

Props

SegmentedControl

Exported types