Actions & Selection
Toggle Group
Toggle Group manages modern single- or multi-select controls with a segmented, toolbar-friendly style. Make the next action easy to recognize. Use visual emphasis deliberately and distinguish an action from a persistent selection or a navigation link. Import it from @/components/kamod-ui/toggle-group.
Source · Design reference · API reference · Theming · Styles
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInstallation
Import ToggleGroup and ToggleGroupItem from @/components/kamod-ui/toggle-group.
pnpm add @kamod-ch/uiCopy an example with @kamod-ch/ui or the matching @kamod-ch/ui/… subpath. The code block switches between those two installs. Connect The Global Theme CSS and Tailwind Source Detection before your first render.
Usage
Use type, variant, size, spacing, and orientation to build compact, modern segmented controls.
import { ToggleGroup } from "@kamod-ch/ui";Choose a complete composition from the examples below; required child components and props vary by pattern.
Component Examples & Variants
Explore Toggle Group in Different Contexts, from the starting pattern to the compositions below. Begin with Single Selection, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API Reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.
Read the Result and Its Implementation Together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the Component Styles Guide for hierarchy and the Theming Guide for shared surfaces and colors. The Accessibility Notes explain what to preserve when making those changes.
Single Selection
Use One Value to Describe the Current Mode. Use single selection when the options represent alternative views or settings within one question. Each ToggleGroupItem value identifies a choice, and the selected presentation lets the reader see which one is currently active.
Decide whether an empty selection is acceptable and handle it deliberately, keep item values stable, and use radios when the surrounding form's question is better expressed as a standard exclusive choice.
import { ToggleGroup, ToggleGroupItem } from "@kamod-ch/ui";
import { AlignCenter, AlignLeft, AlignRight } from "lucide-preact";
export const Example = () => (
<ToggleGroup type="single" defaultValue="left" variant="outline">
<ToggleGroupItem value="left" aria-label="Align left">
<AlignLeft class="size-4" />
</ToggleGroupItem>
<ToggleGroupItem value="center" aria-label="Align center">
<AlignCenter class="size-4" />
</ToggleGroupItem>
<ToggleGroupItem value="right" aria-label="Align right">
<AlignRight class="size-4" />
</ToggleGroupItem>
</ToggleGroup>
);Sizes
Choose a Density that Fits the Labels. Choose a compact or larger group size to match adjacent controls and the available label space. Apply one consistent scale to the local set of choices instead of resizing individual segments independently.
Check the longest translation and icon combination before shrinking the group, and maintain enough spacing around it for comfortable touch interaction.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthSpacing
Tune the Relationship between Choices. Use the group's spacing options to tune how closely its choices sit together. A tight arrangement emphasizes their relationship, while more separation can help longer labels remain readable without changing their selection behavior.
Keep related groups visually consistent and avoid using spacing alone to explain whether the selection is exclusive or multiple.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthVertical
Stack Choices When the Container Is Narrow. Set orientation="vertical" when the choices form a short stack alongside content. The layout still represents one related selection group, so its labels and focus order should remain understandable from top to bottom.
Keep labels aligned and meaningful, verify keyboard movement for the chosen orientation and avoid changing the order simply to fit the visual layout.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthDisabled
Keep Unavailable Choices Understandable. Disable the whole group when the setting is unavailable, or individual items when only some choices are restricted. Keep those choices in context and explain any prerequisite that users can act on.
If the whole group is disabled, keep its current value readable and make clear whether it is a temporary pending state or a lasting restriction.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthCustom Font Weight
Preview a Choice without Losing Legibility. Apply custom item classes to preview different font weights within a segmented selector. Store a stable value for the chosen weight, letting the visible typography illustrate the option without becoming the data model itself.
Keep the stored values separate from the visual sample and make selected state distinct from the weight itself.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthIcon Only
Name Every Mode Explicitly. Use icon-only items for a compact editor-style toolbar when the symbols are recognizable. Provide an accessible name for every choice and consider a Tooltip when the icon's meaning benefits from a short explanation.
Choose symbols that distinguish the options, preserve pressed and focus states, and avoid relying on subtle icon differences that become ambiguous at compact sizes.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthMultiple Selection
Allow a Combination Only When It Has Meaning. Use multiple selection when several formatting options can be active together. Treat the selected values as one collection so external controls and the content being formatted reflect the same combination of choices.
Keep the selected collection synchronized with the application, handle clearing deliberately and make it clear that activating one item does not automatically replace the others.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthPill Style
Use Shape to Support a Lightweight Set of Choices. Set variant="pill" for rounded segments with a chip-like appearance. This changes the group's silhouette while its selection mode and values continue to define whether the options are exclusive or independently selectable.
Keep the pressed state visible in both themes and preserve the same selection semantics as other variants; a change in silhouette should not imply a different behavior.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthControlled
Keep Selection Owned by the Feature It Changes. Pass value and update it through onValueChange when another part of the interface needs the selected options. The group then renders parent-owned state rather than maintaining a second copy of the same preference.
Forward changes to the same state source, distinguish single values from multiple selections, and test updates made outside the group as well as direct activation.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthProps and Data
Configure Toggle Group using the contracts below. Read the documented options alongside the Source Definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.
Props, slots and variants for this component.
Type cards are extracted from this checkout’s TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.
Component Props
? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.ToggleGroup
ToggleGroupProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
defaultValue | Configure
|
disabled | Configure
|
name | Configure
|
onValueChange | Configure
|
orientation | Configure
|
required | Configure
|
size | Configure
|
spacing | Configure
|
type | Configure
|
value | Configure
|
variant | Configure
|
ToggleGroupItem
ToggleGroupItemProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
disabled | Configure
|
onClick | Configure
|
size | Configure
|
value | Configure
|
variant | Configure
|
Data Type Reference
Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the Implementation Source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.
ToggleGroupBase Props
9 declared fieldsToggleGroupBasePropsToggleGroup.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ToggleGroupBaseProps before adapting it.SingleToggleGroup Props
2 declared fieldsSingleToggleGroupPropsToggleGroup.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SingleToggleGroupProps before adapting it.MultipleToggleGroup Props
2 declared fieldsMultipleToggleGroupPropsToggleGroup.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of MultipleToggleGroupProps before adapting it.typeToggleGroup Props
DeclarationToggleGroupPropsToggleGroup.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ToggleGroupProps before adapting it.ToggleGroupItem Props
3 declared fieldsToggleGroupItemPropsToggleGroupItem.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ToggleGroupItemProps before adapting it.valueAccessibility
ToggleGroup groups toggle buttons and defaults to single selection. Each item exposes aria-pressed; the root is a group, not a radiogroup. Do not assume mutually exclusive values imply native radio keyboard behavior.
You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.
Connect the Foundation
Return to Choose and Compose Components to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.
Build the Surrounding Screen
Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.
Make the Result Hold Up
Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.
Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.