ThemeModeSegment
Overview
SThemeModeSegment is a context-bound segmented control bound to the active SConfigProvider theme. It exposes the three ThemeModePreference options — auto (follows the OS prefers-color-scheme), light, and dark — as icon-led segment options, letting users pick a color scheme preference directly. Use it when all three preferences should be visible at a glance, such as in a header, settings panel, or customizer.
Usage
Features
- 🌓 Three options —
auto/light/dark, matching the thememodetype - 🎚 Selection writes the preference through the shared theme context
- 🎨 Inherits
Segmentvisual props (size/shape/fill/ …), withshapedefaulting torounded - 🖼 Scheme icons (monitor / sun / moon) are always rendered;
showLabeladds the localized label next to them (hidden labels still provide accessible names)
Demos
Basic
API
Aria Layer
1ThemeModeSegment
Props
| Prop | Type | Default | Description |
|---|---|---|---|
showLabel | boolean | false | Whether to render the localized label next to the scheme icon. When
`false`, the label stays visually hidden so each option keeps an
accessible name. |
unmountOnHide | boolean | `true` | When `true`, the element will be unmounted on closed state. |
class | ClassValue | — | Additional class names applied to the root element. |
dir | Direction | — | The direction of navigation between items. |
size | ThemeSize | — | Visual size of the component. |
fill | SegmentFill | — | Fill. |
shape | SegmentShape | — | Shape of the component. |
loop | boolean | false | Whether keyboard navigation should loop around |
triggerProps | SegmentTriggerProps | — | Properties forwarded to the trigger element. |
orientation | DataOrientation | — | The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) |
listProps | SegmentListProps | — | Properties forwarded to the list element. |
ui | Partial<SegmentUi> | — | Per-slot class overrides for the component. |
enableIndicator | boolean | — | Whether to enable indicator. |
indicatorProps | SegmentIndicatorProps | — | Properties forwarded to the indicator element. |
activationMode | TabsActivationMode | automatic | Whether a tab is activated automatically (on focus) or manually (on click). |
Notes
Scope
Like SThemeModeSelect and SThemeModeSwitch, SThemeModeSegment is a theme-layer component that operates on the theme context from a parent SConfigProvider. It does not accept a modelValue; the preference is owned by the provider and shared across all theme components. It is the segmented counterpart of SThemeModeSelect — same three options, no dropdown.
Cautions
- The component must be rendered inside a
SConfigProvider, otherwiseuseThemethrows. autois a preference — the resolved scheme (light/dark) still depends on the OSprefers-color-schemeand is exposed aseffectiveModeon the theme context.items,modelValue, anddefaultValueare not exposed: the option list is fixed and the state lives in the theme context.