From cd6975e2f6ab6a11129a053c9d90d0b21fe17347 Mon Sep 17 00:00:00 2001
From: Rohan Chakraborty <irohan1999@gmail.com>
Date: Thu, 12 Mar 2026 09:47:50 +0530
Subject: [PATCH] wip: toggle component

---
 apps/www/src/components/demo/demo.tsx         |  12 +
 apps/www/src/components/playground/index.ts   |   1 +
 .../components/playground/toggle-examples.tsx |  95 +++++
 .../content/docs/components/toggle/demo.ts    | 123 ++++++
 .../content/docs/components/toggle/index.mdx  |  83 ++++
 .../content/docs/components/toggle/props.ts   |  81 ++++
 .../components/icon-button/icon-button.tsx    |   2 +-
 .../toggle/__tests__/toggle.test.tsx          | 364 ++++++++++++++++++
 packages/raystack/components/toggle/index.ts  |   1 +
 .../components/toggle/toggle.module.css       |  99 +++++
 .../raystack/components/toggle/toggle.tsx     |  59 +++
 packages/raystack/index.tsx                   |   1 +
 12 files changed, 920 insertions(+), 1 deletion(-)
 create mode 100644 apps/www/src/components/playground/toggle-examples.tsx
 create mode 100644 apps/www/src/content/docs/components/toggle/demo.ts
 create mode 100644 apps/www/src/content/docs/components/toggle/index.mdx
 create mode 100644 apps/www/src/content/docs/components/toggle/props.ts
 create mode 100644 packages/raystack/components/toggle/__tests__/toggle.test.tsx
 create mode 100644 packages/raystack/components/toggle/index.ts
 create mode 100644 packages/raystack/components/toggle/toggle.module.css
 create mode 100644 packages/raystack/components/toggle/toggle.tsx

diff --git a/apps/www/src/components/demo/demo.tsx b/apps/www/src/components/demo/demo.tsx
index 83d2b8d66..7852cbb87 100644
--- a/apps/www/src/components/demo/demo.tsx
+++ b/apps/www/src/components/demo/demo.tsx
@@ -1,10 +1,16 @@
 'use client';
 
 import {
+  FontBoldIcon,
+  FontItalicIcon,
   InfoCircledIcon,
   Pencil2Icon,
   PlusIcon,
+  TextAlignCenterIcon,
+  TextAlignLeftIcon,
+  TextAlignRightIcon,
   TransformIcon,
+  UnderlineIcon,
   UploadIcon
 } from '@radix-ui/react-icons';
 import * as Apsara from '@raystack/apsara';
@@ -37,6 +43,12 @@ export default function Demo(props: DemoProps) {
       Pencil2Icon,
       InfoCircledIcon,
       UploadIcon,
+      FontBoldIcon,
+      FontItalicIcon,
+      UnderlineIcon,
+      TextAlignLeftIcon,
+      TextAlignCenterIcon,
+      TextAlignRightIcon,
       dayjs
     }
   } = props;
diff --git a/apps/www/src/components/playground/index.ts b/apps/www/src/components/playground/index.ts
index 62ec07833..cd94ee154 100644
--- a/apps/www/src/components/playground/index.ts
+++ b/apps/www/src/components/playground/index.ts
@@ -44,4 +44,5 @@ export * from './tabs-examples';
 export * from './text-area-examples';
 export * from './text-examples';
 export * from './toast-examples';
+export * from './toggle-examples';
 export * from './tooltip-examples';
diff --git a/apps/www/src/components/playground/toggle-examples.tsx b/apps/www/src/components/playground/toggle-examples.tsx
new file mode 100644
index 000000000..8549f5f0e
--- /dev/null
+++ b/apps/www/src/components/playground/toggle-examples.tsx
@@ -0,0 +1,95 @@
+'use client';
+
+import {
+  FontBoldIcon,
+  FontItalicIcon,
+  TextAlignCenterIcon,
+  TextAlignLeftIcon,
+  TextAlignRightIcon,
+  UnderlineIcon
+} from '@radix-ui/react-icons';
+import { Flex, Text, Toggle } from '@raystack/apsara';
+import PlaygroundLayout from './playground-layout';
+
+export function ToggleExamples() {
+  return (
+    <PlaygroundLayout title='Toggle'>
+      <Flex direction='column' gap='large'>
+        <Text size={2} weight={500}>
+          Standalone
+        </Text>
+        <Flex gap='medium' align='center'>
+          <Toggle aria-label='Bold'>
+            <FontBoldIcon />
+          </Toggle>
+          <Toggle aria-label='Bold' defaultPressed>
+            <FontBoldIcon />
+          </Toggle>
+          <Toggle aria-label='Bold' disabled>
+            <FontBoldIcon />
+          </Toggle>
+        </Flex>
+
+        <Text size={2} weight={500}>
+          Sizes
+        </Text>
+        <Flex gap='medium' align='center'>
+          <Toggle size={1} aria-label='Bold'>
+            <FontBoldIcon />
+          </Toggle>
+          <Toggle size={2} aria-label='Bold'>
+            <FontBoldIcon />
+          </Toggle>
+          <Toggle size={3} aria-label='Bold'>
+            <FontBoldIcon />
+          </Toggle>
+          <Toggle size={4} aria-label='Bold'>
+            <FontBoldIcon />
+          </Toggle>
+        </Flex>
+
+        <Text size={2} weight={500}>
+          Toggle.Group (single selection)
+        </Text>
+        <Toggle.Group defaultValue={['center']} aria-label='Text alignment'>
+          <Toggle value='left' aria-label='Align left'>
+            <TextAlignLeftIcon />
+          </Toggle>
+          <Toggle value='center' aria-label='Align center'>
+            <TextAlignCenterIcon />
+          </Toggle>
+          <Toggle value='right' aria-label='Align right'>
+            <TextAlignRightIcon />
+          </Toggle>
+        </Toggle.Group>
+
+        <Text size={2} weight={500}>
+          Toggle.Group (multiple selection)
+        </Text>
+        <Toggle.Group multiple aria-label='Text formatting'>
+          <Toggle value='bold' aria-label='Bold'>
+            <FontBoldIcon />
+          </Toggle>
+          <Toggle value='italic' aria-label='Italic'>
+            <FontItalicIcon />
+          </Toggle>
+          <Toggle value='underline' aria-label='Underline'>
+            <UnderlineIcon />
+          </Toggle>
+        </Toggle.Group>
+
+        <Text size={2} weight={500}>
+          Disabled Group
+        </Text>
+        <Toggle.Group disabled aria-label='Disabled alignment'>
+          <Toggle value='left' aria-label='Align left'>
+            <TextAlignLeftIcon />
+          </Toggle>
+          <Toggle value='center' aria-label='Align center'>
+            <TextAlignCenterIcon />
+          </Toggle>
+        </Toggle.Group>
+      </Flex>
+    </PlaygroundLayout>
+  );
+}
diff --git a/apps/www/src/content/docs/components/toggle/demo.ts b/apps/www/src/content/docs/components/toggle/demo.ts
new file mode 100644
index 000000000..9d7baf3c7
--- /dev/null
+++ b/apps/www/src/content/docs/components/toggle/demo.ts
@@ -0,0 +1,123 @@
+'use client';
+
+import { getPropsString } from '@/lib/utils';
+
+const getCode = (props: any) => {
+  return `<Toggle aria-label="Bold"${getPropsString(props)}>
+  <FontBoldIcon />
+</Toggle>`;
+};
+
+export const playground = {
+  type: 'playground',
+  controls: {
+    defaultPressed: {
+      type: 'checkbox',
+      defaultValue: false
+    },
+    disabled: {
+      type: 'checkbox',
+      defaultValue: false
+    },
+    size: {
+      type: 'select',
+      options: ['1', '2', '3', '4'],
+      defaultValue: '3'
+    }
+  },
+  getCode
+};
+
+export const preview = {
+  type: 'code',
+  code: `<Toggle aria-label="Bold" defaultPressed>
+  <b>B</b>
+</Toggle>`
+};
+
+export const groupDemo = {
+  type: 'code',
+  code: `<Toggle.Group defaultValue={["center"]} aria-label="Text alignment">
+  <Toggle value="left" aria-label="Align left">
+    <TextAlignLeftIcon />
+  </Toggle>
+  <Toggle value="center" aria-label="Align center">
+    <TextAlignCenterIcon />
+  </Toggle>
+  <Toggle value="right" aria-label="Align right">
+    <TextAlignRightIcon />
+  </Toggle>
+</Toggle.Group>`
+};
+
+export const multipleDemo = {
+  type: 'code',
+  code: `<Toggle.Group multiple aria-label="Text formatting">
+  <Toggle value="bold" aria-label="Bold">
+    <FontBoldIcon />
+  </Toggle>
+  <Toggle value="italic" aria-label="Italic">
+    <FontItalicIcon />
+  </Toggle>
+  <Toggle value="underline" aria-label="Underline">
+    <UnderlineIcon />
+  </Toggle>
+</Toggle.Group>`
+};
+
+export const controlledDemo = {
+  type: 'code',
+  code: `function ControlledToggle() {
+  const [pressed, setPressed] = React.useState(false);
+  return (
+    <Toggle
+      aria-label="Star"
+      pressed={pressed}
+      onPressedChange={setPressed}
+    >
+      {pressed ? "★" : "☆"}
+    </Toggle>
+  );
+}`
+};
+
+export const sizeDemo = {
+  type: 'code',
+  code: `<Flex gap="large" align="center">
+  <Toggle size={1} aria-label="Bold">
+    <FontBoldIcon />
+  </Toggle>
+  <Toggle size={2} aria-label="Bold">
+    <FontBoldIcon />
+  </Toggle>
+  <Toggle size={3} aria-label="Bold">
+    <FontBoldIcon />
+  </Toggle>
+  <Toggle size={4} aria-label="Bold">
+    <FontBoldIcon />
+  </Toggle>
+</Flex>`
+};
+
+export const disabledDemo = {
+  type: 'code',
+  tabs: [
+    {
+      name: 'Single',
+      code: `<Toggle aria-label="Bold" disabled>
+  <b>B</b>
+</Toggle>`
+    },
+    {
+      name: 'Group',
+      code: `<Toggle.Group disabled aria-label="Text alignment">
+  <Toggle value="left" aria-label="Align left">
+    <TextAlignLeftIcon />
+  </Toggle>
+  <Toggle value="center" aria-label="Align center">
+    <TextAlignCenterIcon />
+  </Toggle>
+</Toggle.Group>`
+    }
+  ]
+};
diff --git a/apps/www/src/content/docs/components/toggle/index.mdx b/apps/www/src/content/docs/components/toggle/index.mdx
new file mode 100644
index 000000000..311feeca5
--- /dev/null
+++ b/apps/www/src/content/docs/components/toggle/index.mdx
@@ -0,0 +1,83 @@
+---
+title: Toggle
+description: A two-state button that can be toggled on or off, used standalone or within a group.
+source: packages/raystack/components/toggle
+tag: new
+---
+
+import { playground, preview, groupDemo, multipleDemo, sizeDemo, controlledDemo, disabledDemo } from "./demo.ts";
+
+<Demo data={playground} />
+
+## Anatomy
+
+Import and use the component:
+
+```tsx
+import { Toggle } from "@raystack/apsara";
+
+<Toggle aria-label="Bold">B</Toggle>
+```
+
+Use `Toggle.Group` to manage a set of toggles with shared state:
+
+```tsx
+<Toggle.Group defaultValue={["left"]}>
+  <Toggle value="left" aria-label="Align left">L</Toggle>
+  <Toggle value="center" aria-label="Align center">C</Toggle>
+  <Toggle value="right" aria-label="Align right">R</Toggle>
+</Toggle.Group>
+```
+
+## API Reference
+
+### Root
+
+A two-state button that can be toggled on or off.
+
+<auto-type-table path="./props.ts" name="ToggleProps" />
+
+### Group
+
+Groups multiple toggle buttons and manages their shared pressed state.
+
+<auto-type-table path="./props.ts" name="ToggleGroupProps" />
+
+## Examples
+
+### Group
+
+Use `Toggle.Group` for exclusive or multi-select toggle sets. By default, only one toggle can be pressed at a time.
+
+<Demo data={groupDemo} />
+
+### Multiple Selection
+
+Set `multiple` on the group to allow more than one toggle to be pressed simultaneously.
+
+<Demo data={multipleDemo} />
+
+### Size
+
+The toggle supports four sizes matching the icon button sizes.
+
+<Demo data={sizeDemo} />
+
+### Controlled
+
+Control the pressed state programmatically.
+
+<Demo data={controlledDemo} />
+
+### Disabled
+
+Disable individual toggles or the entire group.
+
+<Demo data={disabledDemo} />
+
+## Accessibility
+
+- Uses native `<button>` element with `aria-pressed` for toggle state
+- Supports keyboard activation with Space and Enter keys
+- `Toggle.Group` renders with `role="group"` and supports arrow key navigation
+- Use `aria-label` on each toggle to provide an accessible name when using icon-only content
diff --git a/apps/www/src/content/docs/components/toggle/props.ts b/apps/www/src/content/docs/components/toggle/props.ts
new file mode 100644
index 000000000..52d943314
--- /dev/null
+++ b/apps/www/src/content/docs/components/toggle/props.ts
@@ -0,0 +1,81 @@
+export interface ToggleProps {
+  /** Unique identifier for the toggle when used inside a `Toggle.Group`. */
+  value?: string;
+
+  /**
+   * The default pressed state (uncontrolled).
+   * @defaultValue false
+   */
+  defaultPressed?: boolean;
+
+  /** The controlled pressed state. */
+  pressed?: boolean;
+
+  /** Event handler called when the pressed state changes. */
+  onPressedChange?: (pressed: boolean, event: Event) => void;
+
+  /**
+   * The size of the toggle.
+   * @defaultValue 3
+   */
+  size?: 1 | 2 | 3 | 4;
+
+  /**
+   * When true, prevents the user from interacting with the toggle.
+   * @defaultValue false
+   */
+  disabled?: boolean;
+
+  /** Additional CSS class names. */
+  className?: string;
+
+  /**
+   * Allows you to replace the component's HTML element with a different tag, or compose it with another component.
+   *
+   * @remarks `ReactElement | function`
+   */
+  render?:
+    | React.ReactElement
+    | ((
+        props: React.HTMLAttributes<HTMLElement>,
+        state: { pressed: boolean; disabled: boolean }
+      ) => React.ReactElement);
+}
+
+export interface ToggleGroupProps {
+  /** The default pressed values (uncontrolled). */
+  defaultValue?: string[];
+
+  /** The controlled pressed values. */
+  value?: string[];
+
+  /** Event handler called when the pressed values change. */
+  onValueChange?: (value: string[], event: Event) => void;
+
+  /**
+   * When true, multiple toggles can be pressed at the same time.
+   * @defaultValue false
+   */
+  multiple?: boolean;
+
+  /**
+   * When true, prevents user interaction with all toggles in the group.
+   * @defaultValue false
+   */
+  disabled?: boolean;
+
+  /**
+   * The orientation of the toggle group.
+   * @defaultValue "horizontal"
+   */
+  orientation?: 'horizontal' | 'vertical';
+
+  /**
+   * When true, keyboard focus wraps from the last item to the first.
+   * @defaultValue true
+   */
+  loopFocus?: boolean;
+
+  /** Additional CSS class names. */
+  className?: string;
+}
diff --git a/packages/raystack/components/icon-button/icon-button.tsx b/packages/raystack/components/icon-button/icon-button.tsx
index 40199089a..ecc36f2fd 100644
--- a/packages/raystack/components/icon-button/icon-button.tsx
+++ b/packages/raystack/components/icon-button/icon-button.tsx
@@ -1,4 +1,4 @@
-import { VariantProps, cva } from 'class-variance-authority';
+import { cva, VariantProps } from 'class-variance-authority';
 import { ElementRef, forwardRef } from 'react';
 import { Flex } from '../flex';
 
diff --git a/packages/raystack/components/toggle/__tests__/toggle.test.tsx b/packages/raystack/components/toggle/__tests__/toggle.test.tsx
new file mode 100644
index 000000000..dad17cd80
--- /dev/null
+++ b/packages/raystack/components/toggle/__tests__/toggle.test.tsx
@@ -0,0 +1,364 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+import { Toggle } from '../toggle';
+import styles from '../toggle.module.css';
+
+describe('Toggle', () => {
+  describe('Basic Rendering', () => {
+    it('renders a button element', () => {
+      render(<Toggle aria-label='Bold'>B</Toggle>);
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toBeInTheDocument();
+    });
+
+    it('applies toggle class', () => {
+      render(<Toggle aria-label='Bold'>B</Toggle>);
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toHaveClass(styles.toggle);
+    });
+
+    it('applies custom className', () => {
+      render(
+        <Toggle aria-label='Bold' className='custom'>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toHaveClass('custom');
+      expect(toggle).toHaveClass(styles.toggle);
+    });
+
+    it('forwards ref correctly', () => {
+      const ref = vi.fn();
+      render(
+        <Toggle ref={ref} aria-label='Bold'>
+          B
+        </Toggle>
+      );
+      expect(ref).toHaveBeenCalled();
+    });
+
+    it('renders children', () => {
+      render(<Toggle aria-label='Bold'>Bold Text</Toggle>);
+      expect(screen.getByText('Bold Text')).toBeInTheDocument();
+    });
+  });
+
+  describe('Size Variants', () => {
+    it('applies default size class (size 3)', () => {
+      render(<Toggle aria-label='Bold'>B</Toggle>);
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toHaveClass(styles['size-3']);
+    });
+
+    it('applies size 1 class', () => {
+      render(
+        <Toggle aria-label='Bold' size={1}>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toHaveClass(styles['size-1']);
+    });
+
+    it('applies size 3 class', () => {
+      render(
+        <Toggle aria-label='Bold' size={3}>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toHaveClass(styles['size-3']);
+    });
+
+    it('applies size 4 class', () => {
+      render(
+        <Toggle aria-label='Bold' size={4}>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toHaveClass(styles['size-4']);
+    });
+  });
+
+  describe('Pressed State', () => {
+    it('is not pressed by default', () => {
+      render(<Toggle aria-label='Bold'>B</Toggle>);
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toHaveAttribute('aria-pressed', 'false');
+    });
+
+    it('renders as pressed with defaultPressed', () => {
+      render(
+        <Toggle aria-label='Bold' defaultPressed>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toHaveAttribute('aria-pressed', 'true');
+    });
+
+    it('renders as pressed with controlled pressed prop', () => {
+      render(
+        <Toggle aria-label='Bold' pressed>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toHaveAttribute('aria-pressed', 'true');
+    });
+
+    it('toggles pressed state on click', () => {
+      render(<Toggle aria-label='Bold'>B</Toggle>);
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+
+      expect(toggle).toHaveAttribute('aria-pressed', 'false');
+      fireEvent.click(toggle);
+      expect(toggle).toHaveAttribute('aria-pressed', 'true');
+      fireEvent.click(toggle);
+      expect(toggle).toHaveAttribute('aria-pressed', 'false');
+    });
+  });
+
+  describe('Event Handling', () => {
+    it('calls onPressedChange when toggled', () => {
+      const handleChange = vi.fn();
+      render(
+        <Toggle aria-label='Bold' onPressedChange={handleChange}>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      fireEvent.click(toggle);
+
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith(true, expect.anything());
+    });
+
+    it('supports keyboard activation with Space', async () => {
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+      render(
+        <Toggle aria-label='Bold' onPressedChange={handleChange}>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      toggle.focus();
+      await user.keyboard('[Space]');
+
+      expect(handleChange).toHaveBeenCalledWith(true, expect.anything());
+    });
+
+    it('supports keyboard activation with Enter', async () => {
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+      render(
+        <Toggle aria-label='Bold' onPressedChange={handleChange}>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      toggle.focus();
+      await user.keyboard('[Enter]');
+
+      expect(handleChange).toHaveBeenCalledWith(true, expect.anything());
+    });
+  });
+
+  describe('Disabled State', () => {
+    it('does not toggle when disabled', () => {
+      const handleChange = vi.fn();
+      render(
+        <Toggle aria-label='Bold' disabled onPressedChange={handleChange}>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      fireEvent.click(toggle);
+
+      expect(handleChange).not.toHaveBeenCalled();
+    });
+
+    it('is disabled when disabled prop is set', () => {
+      render(
+        <Toggle aria-label='Bold' disabled>
+          B
+        </Toggle>
+      );
+      const toggle = screen.getByRole('button', { name: 'Bold' });
+      expect(toggle).toBeDisabled();
+    });
+  });
+});
+
+describe('Toggle.Group', () => {
+  describe('Basic Rendering', () => {
+    it('renders a group element', () => {
+      render(
+        <Toggle.Group aria-label='Text alignment'>
+          <Toggle value='left' aria-label='Left'>
+            L
+          </Toggle>
+          <Toggle value='center' aria-label='Center'>
+            C
+          </Toggle>
+        </Toggle.Group>
+      );
+      const group = screen.getByRole('group', { name: 'Text alignment' });
+      expect(group).toBeInTheDocument();
+    });
+
+    it('applies group class', () => {
+      render(
+        <Toggle.Group aria-label='Text alignment'>
+          <Toggle value='left' aria-label='Left'>
+            L
+          </Toggle>
+        </Toggle.Group>
+      );
+      const group = screen.getByRole('group', { name: 'Text alignment' });
+      expect(group).toHaveClass(styles.group);
+    });
+
+    it('applies custom className', () => {
+      render(
+        <Toggle.Group aria-label='Text alignment' className='custom'>
+          <Toggle value='left' aria-label='Left'>
+            L
+          </Toggle>
+        </Toggle.Group>
+      );
+      const group = screen.getByRole('group', { name: 'Text alignment' });
+      expect(group).toHaveClass('custom');
+      expect(group).toHaveClass(styles.group);
+    });
+
+    it('forwards ref correctly', () => {
+      const ref = vi.fn();
+      render(
+        <Toggle.Group ref={ref} aria-label='Text alignment'>
+          <Toggle value='left' aria-label='Left'>
+            L
+          </Toggle>
+        </Toggle.Group>
+      );
+      expect(ref).toHaveBeenCalled();
+    });
+  });
+
+  describe('Selection', () => {
+    it('supports single selection by default', () => {
+      render(
+        <Toggle.Group defaultValue={['left']} aria-label='Text alignment'>
+          <Toggle value='left' aria-label='Left'>
+            L
+          </Toggle>
+          <Toggle value='center' aria-label='Center'>
+            C
+          </Toggle>
+        </Toggle.Group>
+      );
+      expect(screen.getByRole('button', { name: 'Left' })).toHaveAttribute(
+        'aria-pressed',
+        'true'
+      );
+      expect(screen.getByRole('button', { name: 'Center' })).toHaveAttribute(
+        'aria-pressed',
+        'false'
+      );
+    });
+
+    it('toggles selection on click', () => {
+      render(
+        <Toggle.Group defaultValue={['left']} aria-label='Text alignment'>
+          <Toggle value='left' aria-label='Left'>
+            L
+          </Toggle>
+          <Toggle value='center' aria-label='Center'>
+            C
+          </Toggle>
+        </Toggle.Group>
+      );
+
+      fireEvent.click(screen.getByRole('button', { name: 'Center' }));
+      expect(screen.getByRole('button', { name: 'Center' })).toHaveAttribute(
+        'aria-pressed',
+        'true'
+      );
+      expect(screen.getByRole('button', { name: 'Left' })).toHaveAttribute(
+        'aria-pressed',
+        'false'
+      );
+    });
+
+    it('supports multiple selection', () => {
+      render(
+        <Toggle.Group multiple aria-label='Formatting'>
+          <Toggle value='bold' aria-label='Bold'>
+            B
+          </Toggle>
+          <Toggle value='italic' aria-label='Italic'>
+            I
+          </Toggle>
+        </Toggle.Group>
+      );
+
+      fireEvent.click(screen.getByRole('button', { name: 'Bold' }));
+      fireEvent.click(screen.getByRole('button', { name: 'Italic' }));
+
+      expect(screen.getByRole('button', { name: 'Bold' })).toHaveAttribute(
+        'aria-pressed',
+        'true'
+      );
+      expect(screen.getByRole('button', { name: 'Italic' })).toHaveAttribute(
+        'aria-pressed',
+        'true'
+      );
+    });
+
+    it('calls onValueChange when selection changes', () => {
+      const handleChange = vi.fn();
+      render(
+        <Toggle.Group onValueChange={handleChange} aria-label='Text alignment'>
+          <Toggle value='left' aria-label='Left'>
+            L
+          </Toggle>
+          <Toggle value='center' aria-label='Center'>
+            C
+          </Toggle>
+        </Toggle.Group>
+      );
+
+      fireEvent.click(screen.getByRole('button', { name: 'Left' }));
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith(['left'], expect.anything());
+    });
+  });
+
+  describe('Disabled State', () => {
+    it('disables all toggles when group is disabled', () => {
+      render(
+        <Toggle.Group disabled aria-label='Text alignment'>
+          <Toggle value='left' aria-label='Left'>
+            L
+          </Toggle>
+          <Toggle value='center' aria-label='Center'>
+            C
+          </Toggle>
+        </Toggle.Group>
+      );
+
+      expect(screen.getByRole('button', { name: 'Left' })).toHaveAttribute(
+        'aria-disabled',
+        'true'
+      );
+      expect(screen.getByRole('button', { name: 'Center' })).toHaveAttribute(
+        'aria-disabled',
+        'true'
+      );
+    });
+  });
+});
diff --git a/packages/raystack/components/toggle/index.ts b/packages/raystack/components/toggle/index.ts
new file mode 100644
index 000000000..6618bb578
--- /dev/null
+++ b/packages/raystack/components/toggle/index.ts
@@ -0,0 +1 @@
+export { Toggle } from './toggle';
diff --git a/packages/raystack/components/toggle/toggle.module.css b/packages/raystack/components/toggle/toggle.module.css
new file mode 100644
index 000000000..4a264f800
--- /dev/null
+++ b/packages/raystack/components/toggle/toggle.module.css
@@ -0,0 +1,99 @@
+.toggle {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  color: var(--rs-color-foreground-base-secondary);
+  cursor: pointer;
+  padding: var(--rs-space-1);
+  transition: color 0.2s ease;
+  background-color: var(--rs-color-background-base-secondary);
+  border: 0.5px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-1);
+}
+.toggleContent {
+  border-radius: var(--rs-radius-1);
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.toggleContent > * {
+  width: 100%;
+  height: 100%;
+}
+
+.toggle:hover,
+.toggle[data-pressed] {
+  color: var(--rs-color-foreground-base-primary);
+}
+.toggle:hover .toggleContent,
+.toggle[data-pressed] .toggleContent {
+  background-color: var(--rs-color-background-base-primary-hover);
+}
+
+.toggle[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+  pointer-events: none;
+}
+
+.size-1 {
+  width: var(--rs-space-4);
+  height: var(--rs-space-4);
+}
+
+.size-2 {
+  width: var(--rs-space-5);
+  height: var(--rs-space-5);
+}
+
+.size-3 {
+  width: var(--rs-space-6);
+  height: var(--rs-space-6);
+}
+
+.size-4 {
+  width: var(--rs-space-7);
+  height: var(--rs-space-7);
+}
+
+.group {
+  display: inline-flex;
+  align-items: center;
+  gap: 1px;
+  padding: var(--rs-space-1);
+  background-color: var(--rs-color-background-base-secondary);
+  border: 0.5px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-1);
+  overflow: clip;
+}
+
+/* Toggle inside Group — strip standalone container styles.
+   Border-radius is handled by the group's overflow: clip. */
+.group .toggle {
+  background-color: transparent;
+  border: none;
+  border-radius: 0;
+}
+
+.group .toggle:hover {
+  background-color: var(--rs-color-background-base-primary);
+  box-shadow: var(--rs-shadow-inset);
+}
+
+.group .toggle[data-pressed] {
+  background-color: var(--rs-color-background-base-primary);
+  box-shadow: var(--rs-shadow-inset);
+}
+
+/* Vertical group */
+.group[data-orientation="vertical"] {
+  flex-direction: column;
+}
+
+.group[data-disabled] {
+  opacity: 0.5;
+  pointer-events: none;
+}
diff --git a/packages/raystack/components/toggle/toggle.tsx b/packages/raystack/components/toggle/toggle.tsx
new file mode 100644
index 000000000..b5caf0346
--- /dev/null
+++ b/packages/raystack/components/toggle/toggle.tsx
@@ -0,0 +1,59 @@
+'use client';
+
+import { Toggle as TogglePrimitive } from '@base-ui/react/toggle';
+import { ToggleGroup as ToggleGroupPrimitive } from '@base-ui/react/toggle-group';
+import { cva, cx, type VariantProps } from 'class-variance-authority';
+import { ElementRef, forwardRef } from 'react';
+
+import styles from './toggle.module.css';
+
+const toggleVariants = cva(styles.toggle, {
+  variants: {
+    size: {
+      1: styles['size-1'],
+      2: styles['size-2'],
+      3: styles['size-3'],
+      4: styles['size-4']
+    }
+  },
+  defaultVariants: {
+    size: 3
+  }
+});
+
+export interface ToggleProps
+  extends TogglePrimitive.Props,
+    VariantProps<typeof toggleVariants> {
+  size?: 1 | 2 | 3 | 4;
+}
+
+const ToggleRoot = forwardRef<ElementRef<typeof TogglePrimitive>, ToggleProps>(
+  ({ className, children, size, ...props }, ref) => (
+    <TogglePrimitive
+      ref={ref}
+      className={toggleVariants({ size, className })}
+      {...props}
+    >
+      <span className={styles.toggleContent}>{children}</span>
+    </TogglePrimitive>
+  )
+);
+
+ToggleRoot.displayName = 'Toggle';
+
+const ToggleGroup = forwardRef<
+  ElementRef<typeof ToggleGroupPrimitive>,
+  ToggleGroupPrimitive.Props
+>(({ className, ...props }, ref) => (
+  <ToggleGroupPrimitive
+    ref={ref}
+    className={cx(styles.group, className)}
+    {...props}
+  />
+));
+
+ToggleGroup.displayName = 'Toggle.Group';
+
+export const Toggle = Object.assign(ToggleRoot, {
+  Group: ToggleGroup
+});
diff --git a/packages/raystack/index.tsx b/packages/raystack/index.tsx
index 95a9e5310..6306411c0 100644
--- a/packages/raystack/index.tsx
+++ b/packages/raystack/index.tsx
@@ -68,4 +68,5 @@ export {
   useTheme
 } from './components/theme-provider';
 export { ToastContainer, toast } from './components/toast';
+export { Toggle } from './components/toggle';
 export { Tooltip } from './components/tooltip';