> For the complete documentation index, see [llms.txt](https://docs.frayme.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frayme.ai/components/components/forms/segmented-control.md).

# SegmentedControl

Inline exclusive option group (a view/sort/density switch): a rounded track of segments where the selected one gets a raised pill (aria-pressed). Icons resolve against the closed registry. Use { $bindState } on value for two-way binding; clicking a segment emits change.

## Example

```json
{
  "root": "segmented-control",
  "elements": {
    "segmented-control": {
      "type": "SegmentedControl",
      "props": {
        "options": [
          {
            "label": "List",
            "value": "list"
          },
          {
            "label": "Grid",
            "value": "grid"
          }
        ],
        "value": "list"
      }
    }
  }
}
```

## Props

| Prop             | Type                                                 | Description                                                                                                                                                            |
| ---------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options`        | `({ label: string, value: string, icon: string })[]` | The exclusive segments ({ label, value, icon? }). Required content.                                                                                                    |
| `value`          | `string`                                             | The selected segment value. Use { $bindState } for two-way binding.                                                                                                    |
| `size`           | `"sm" \| "md" \| "lg"`                               | Track height/font-size/padding token (default `md`); use `sm` in dense toolbars, `lg` for touch or prominent switches.                                                 |
| `fullWidth`      | `boolean`                                            | Stretch the track to the container width with equal-width segments.                                                                                                    |
| `iconOnly`       | `boolean`                                            | Show only the icon for each segment (label moves to aria-label).                                                                                                       |
| `accent`         | `string`                                             | Fill color of the selected pill (default the card token — a raised neutral pill); every segment’s keyboard focus ring derives from it too (default the primary token). |
| `accentText`     | `string`                                             | Text color on the selected pill (default the foreground token; primary-foreground when `accent` is set, so a saturated fill keeps readable ink).                       |
| `trackColor`     | `string`                                             | Resting track colour behind the pills — the rounded rail the segments sit on (default the muted token).                                                                |
| `connectorColor` | `string`                                             | Colour of the thin dividers between resting (unselected) segments (default the border token; suppressed beside the selected pill).                                     |
| `disabled`       | `boolean`                                            | Grey out the whole track (60% opacity, not-allowed cursor) and block selecting any segment (default false).                                                            |
| `radiusValue`    | `string \| number`                                   | Exact corner radius shared by the rail and the segment pills (e.g. "12px" or "0.75rem"; default the frayme radius). Overrides the default rounding.                    |

## Events

### change

A different segment was clicked/selected; params carry { value } (the newly selected segment's value).

| Key     | Type      | Description                                           |
| ------- | --------- | ----------------------------------------------------- |
| `value` | `unknown` | Optional. The new value after the change.             |
| `name`  | `string`  | Optional. The control’s machine name when it has one. |

See [Events](/components/events.md) for the full payload contract.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.frayme.ai/components/components/forms/segmented-control.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.