@versini/ui-togglegroup

An accessible React toggle button group component built with TypeScript and TailwindCSS.

The ToggleGroup component provides grouped toggle buttons for single-select usage with proper accessibility, typeahead support (via Radix), theming, sizing and focus management.

Table of Contents

• Features
• Installation
• Usage
• Examples
• API

Features

• 🔢 Grouped Selection: Manage a set of related options with single selection
• ♿ Accessible: Built atop Radix primitives with robust a11y patterns
• 🎨 Theming & Sizes: Supports light/dark/system modes & small | medium | large sizes
• 🎯 Focus Styles: Independent focusMode to align with design tokens
• ⌨️ Keyboard Friendly: Arrow key navigation & typeahead labeling
• 🧪 Type Safe: Strongly typed props and context sharing

Installation

npm install @versini/ui-togglegroup

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

import { ToggleGroup } from "@versini/ui-togglegroup";

function App() {
  const [selected, setSelected] = useState("left");

  return (
    <ToggleGroup
      value={selected}
      onChange={setSelected}
      items={[
        { value: "left", label: "Left" },
        { value: "center", label: "Center" },
        { value: "right", label: "Right" }
      ]}
    />
  );
}

Examples

Large Size Group

<ToggleGroup size="large" value={alignment} onValueChange={setAlignment}>
  <ToggleGroupItem value="left" />
  <ToggleGroupItem value="center" />
  <ToggleGroupItem value="right" />
</ToggleGroup>

Themed Group (Dark)

<ToggleGroup
  mode="dark"
  focusMode="light"
  value={theme}
  onValueChange={setTheme}
>
  <ToggleGroupItem value="auto" />
  <ToggleGroupItem value="light" />
  <ToggleGroupItem value="dark" />
</ToggleGroup>

API

ToggleGroup Props

| Prop | Type | Default | Description | | --------------- | ------------------------- | -------- | ----------------------------------------- | ------------- | --------------------- | -------------------------- | | value | string | - | Current selected value (controlled). | | defaultValue | string | - | Initial value (uncontrolled). | | onValueChange | (value: string) => void | - | Fired when selection changes. | | disabled | boolean | - | Disable the entire group. | | mode | "dark" | "light" | "system" | "alt-system" | "system" | Color / theme mode. | | focusMode | "dark" | "light" | "system" | "alt-system" | "system" | Color mode for focus ring. | | size | "small" | "medium" | "large" | "medium" | Visual size of items. | | className | string | - | Extra class(es) applied to container. | | children | React.ReactNode | - | One or more ToggleGroupItem components. |

Inherits other valid props from @radix-ui/react-toggle-group single variant (except type, defaultValue already controlled internally).

ToggleGroupItem Props

| Prop | Type | Default | Description | | ---------- | --------- | ------- | -------------------------------------- | | value | string | - | Value represented by this toggle item. | | disabled | boolean | - | Disable just this item. |

Item content is the value string by default; you can customize by extending the component if needed.