toggle-group.tsx

Overview

The toggle-group.tsx file defines a reusable and customizable Toggle Group React component built on top of the @radix-ui/react-toggle-group primitives. This component provides a grouped toggle button interface supporting multiple styling variants and sizes, facilitating consistent UI controls in applications.

The file exports two main components:

• ToggleGroup: The container component representing the whole toggle group.

• ToggleGroupItem: Individual toggle buttons within the group.

These components leverage React context to share styling variants and sizes between the group and its items, ensuring consistent appearance and behavior. The use of class-variance-authority for managing variants combined with utility CSS classes enables flexible styling.

Components and Functions

1. ToggleGroup

Description

The ToggleGroup component acts as a wrapper for one or more ToggleGroupItem components. It manages the overall styling, variant, and size context for its children toggle items.

Props

• Inherits all props from ToggleGroupPrimitive.Root (from @radix-ui/react-toggle-group), which includes accessibility and toggle-group behavior props such as type (single/multiple), value, defaultValue, onValueChange, etc.

• variant: Optional styling variant (string) passed to customize appearance (e.g., "default", "outline").

• size: Optional size variant (string) for controlling component dimensions (e.g., "default", "sm", "lg").

• className: Optional additional CSS classes for customization.

• children: React nodes, expected to be one or more ToggleGroupItem components.

Returns

A styled ToggleGroupPrimitive.Root component wrapping the children and providing a React context with the variant and size values.

Usage Example

<ToggleGroup type="single" variant="outline" size="sm" defaultValue="left">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>

2. ToggleGroupItem

Description

Represents an individual toggle button inside the ToggleGroup. It consumes the variant and size from the nearest ToggleGroup context but can also accept its own variant and size props to override the context.

Props

• Inherits all props from ToggleGroupPrimitive.Item which includes value, disabled, and event handlers.

• variant: Optional styling variant to override context.

• size: Optional size variant to override context.

• className: Optional additional CSS classes.

• children: React nodes to display inside the toggle item (usually text or icons).

Returns

A styled ToggleGroupPrimitive.Item component interacting with the toggle group.

Usage Example

<ToggleGroupItem value="bold">Bold</ToggleGroupItem>

When used inside a ToggleGroup, it automatically receives the variant and size unless explicitly overridden.

Implementation Details

• Styling Variants:
  The styling variants are managed through the toggleVariants function imported from @/components/ui/toggle. This function is configured using class-variance-authority to apply different CSS classes based on variant and size props.

• Context API:
  The ToggleGroupContext React context shares the current variant and size from the ToggleGroup component with all nested ToggleGroupItem components. This ensures consistent styling without prop drilling.

• Class Name Merging:
  The utility function cn (imported from @/lib/utils) merges class names conditionally, combining default classes with variant-specific classes and any user-provided classes.

• Radix UI Integration:
  By wrapping @radix-ui/react-toggle-group primitives, this component inherits accessibility, keyboard navigation, and ARIA attributes out of the box.

• Data Attributes for Styling:
  Custom data-variant and data-size attributes are added to the DOM elements for easier CSS targeting and styling.

Interaction with the System

• Dependency on toggleVariants:
  This file depends on the toggleVariants utility for CSS class generation based on the variant and size props.

• Usage in UI Library:
  ToggleGroup and ToggleGroupItem are likely part of a UI component library or design system. They provide consistent toggle button groups across the application.

• Integration with Radix UI:
  The components rely on Radix UI's toggle group primitives for robust accessibility and keyboard handling, making them extensible and accessible.

• Utility Functions:
  The cn function (class name merger) is a local utility used throughout the project for composing class names.

Mermaid Diagram

classDiagram
    class ToggleGroup {
        +props: ToggleGroupPrimitive.Root props & VariantProps
        +render()
    }
    class ToggleGroupItem {
        +props: ToggleGroupPrimitive.Item props & VariantProps
        +render()
    }
    class ToggleGroupContext {
        +variant: string
        +size: string
    }

    ToggleGroup "1" --> "many" ToggleGroupItem : provides context
    ToggleGroup ..> ToggleGroupContext : uses React context
    ToggleGroupItem ..> ToggleGroupContext : consumes context

Summary

This file provides a composable and stylable toggle group UI component with tightly integrated variant and size management through React context. Leveraging Radix UI primitives ensures accessibility and consistent toggle group behavior, while the use of class-variance-authority and a utility class merging function allow flexible styling. It fits into a UI component ecosystem as a building block for toggle controls with customizable appearances.