SegmentGroup
Introduction
An option-selector control that allows users to toggle between multiple mutually exclusive values within a single consolidated track. Similar to a radio group but styled with an animated, sliding indicator highlighting the active selection. Primarily used for view toggles, dashboard filter ranges, panel options, and status selections.
The SegmentGroup component is fully integrated as an interactive segmentGroup block in the Page Builder, allowing content authors and developers to easily configure custom items, orientations, and size scales directly within the CMS.
Usage
These examples illustrate how content editors bind and structure segment group components.
1. Standard View Layout Selector (Fitted & Horizontal)
A standard layout selector option with two values that stretches to fill the container's width, commonly used for toggling between List and Grid representations of content.
{
"type": "segmentGroup",
"defaultValue": "grid",
"fitted": true,
"interactive": true,
"items": [
{ "label": "List View", "value": "list" },
{ "label": "Grid View", "value": "grid" }
]
}
2. Prominent Time Range Selector (Large Size Scale)
Features a larger visual size scale, rendering a prominent filter control suitable for main dashboard dashboards and analytics platforms.
{
"type": "segmentGroup",
"defaultValue": "30d",
"size": "lg",
"interactive": true,
"items": [
{ "label": "7 Days", "value": "7d" },
{ "label": "30 Days", "value": "30d" },
{ "label": "90 Days", "value": "90d" }
]
}
3. Compact Vertical System Selection with Disabled Options
Demonstrates a vertical arrangement with custom item constraints. Useful for side panels or settings dialogs where certain options might be temporarily locked or restricted.
{
"type": "segmentGroup",
"label": "Notification Frequency",
"defaultValue": "daily",
"orientation": "vertical",
"size": "sm",
"interactive": true,
"items": [
{ "label": "Real-time Alerts", "value": "instant", "disabled": true },
{ "label": "Daily Digest", "value": "daily" },
{ "label": "Weekly Summary", "value": "weekly" }
]
}
Props
| Property | CMS Field Type | Default | Description / Supported Options |
|---|---|---|---|
Label Text (label) | string | - | Optional group label positioned above the segmented controller track. |
Default Value (defaultValue) | string | - | The value of the option that should be active by default upon initial render. |
Items List (items) | list | - | Array of selection options containing label (text), value (ID), and optional disabled status. |
Orientation (orientation) | select | "horizontal" | Directional layout flow of the segment buttons. • Options: "horizontal", "vertical". |
Fitted Layout (fitted) | boolean | false | Whether individual segments expand evenly to stretch and fill the parent container's width. |
Size Scale (size) | select | "md" | Controls the vertical height, padding, and text-sizing of segment items. • Options: "xs", "sm", "md", "lg", "xl". |
Force Interactive (interactive) | boolean | true | Hydrates the component as a Preact interactive island so click events trigger option changes immediately. |
Developer Notes & Accessibility
- Hydration Island: As an input selector that captures active click interactions and computes slide offsets, the SegmentGroup operates as an interactive client-side island by default (
"interactive": true). - WAI-ARIA Compliance: Under the hood, this component compiles to a fully-accessible radio group button container (
role="radiogroup",aria-label) containing individual options (role="radio"). Keyboard arrow keys automatically cycle through available values, and focus transitions follow correct ARIA tabs standards. - Form Integration: It outputs native hidden
<input type="radio">controls bound to each active item. This ensures form submissions (such as standard POST requests) correctly capture values without requiring extra state synchronization in Javascript.