@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, 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: radiogroup / radio semantics with roving focus, no third-party runtime dependencies
• 🎨 Theming & Sizes: Inherits light/dark theming from the surrounding theme, plus small | medium | large sizes
• ⌨️ Keyboard Friendly: Arrow keys (both axes), Home/End/PageUp/PageDown move focus and skip disabled items; Enter/Space toggle
• 🧪 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

Uncontrolled

Use defaultValue when you don't need to manage the selection state yourself:

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

function App() {
  return (
    <ToggleGroup defaultValue="center">
      <ToggleGroupItem value="left" />
      <ToggleGroupItem value="center" />
      <ToggleGroupItem value="right" />
    </ToggleGroup>
  );
}

Controlled

Use value and onValueChange when you need full control over the selection:

import { useState } from "react";
import { ToggleGroup, ToggleGroupItem } from "@versini/ui-togglegroup";

function App() {
  const [alignment, setAlignment] = useState("left");

  return (
    <ToggleGroup value={alignment} onValueChange={setAlignment}>
      <ToggleGroupItem value="left" />
      <ToggleGroupItem value="center" />
      <ToggleGroupItem value="right" />
    </ToggleGroup>
  );
}

Examples

Large Size Group

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

Theme Picker

<ToggleGroup 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. Reports "" when nothing is pressed. | | disabled | boolean | false | Disable the entire group. | | size | "small" \| "medium" \| "large" | "medium" | Visual size of items. | | flat | boolean | false | Render a flat solid background instead of the gradient overlay. | | className | string | - | Extra class(es) applied to container. | | children | React.ReactNode | - | One or more ToggleGroupItem components. |

Selecting the already-selected item clears the selection and reports an empty string, rather than being a no-op as in a plain radio group.

ToggleGroupItem Props

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

Item content is the value string by default; pass children to customize it.

ToggleGroupItem accepts all native <button> props except value and type. Extra props are forwarded to the underlying button, and className is merged with the component's own classes.