diff --git a/docs-ui/src/app/components/card/components.tsx b/docs-ui/src/app/components/card/components.tsx
index 89ab09d47d..08fa940be8 100644
--- a/docs-ui/src/app/components/card/components.tsx
+++ b/docs-ui/src/app/components/card/components.tsx
@@ -10,7 +10,7 @@ import { Text } from '../../../../../packages/ui/src/components/Text/Text';
 
 export const Default = () => {
   return (
-    <Card>
+    <Card style={{ width: '300px', height: '200px' }}>
       <CardHeader>Header</CardHeader>
       <CardBody>Body</CardBody>
       <CardFooter>Footer</CardFooter>
diff --git a/docs-ui/src/app/components/menu/components.tsx b/docs-ui/src/app/components/menu/components.tsx
index 1c9aa2598d..d4ddfbf4ba 100644
--- a/docs-ui/src/app/components/menu/components.tsx
+++ b/docs-ui/src/app/components/menu/components.tsx
@@ -12,17 +12,35 @@ import {
 } from '../../../../../packages/ui/src/components/Menu/Menu';
 import { Button } from '../../../../../packages/ui/src/components/Button/Button';
 import { MemoryRouter } from 'react-router-dom';
-import { RiFileLine, RiFolderLine, RiImageLine } from '@remixicon/react';
+import {
+  RiChat1Line,
+  RiFileLine,
+  RiFolderLine,
+  RiImageLine,
+  RiSettingsLine,
+  RiShareBoxLine,
+} from '@remixicon/react';
 
 export const Preview = () => (
   <MemoryRouter>
     <MenuTrigger>
-      <Button variant="secondary">Menu</Button>
+      <Button aria-label="Menu">Menu</Button>
       <Menu>
-        <MenuItem>New File</MenuItem>
-        <MenuItem>Open File</MenuItem>
-        <MenuItem>Save</MenuItem>
-        <MenuItem>Save As...</MenuItem>
+        <MenuItem>Edit</MenuItem>
+        <MenuItem>Duplicate</MenuItem>
+        <MenuItem>Rename</MenuItem>
+        <MenuSeparator />
+        <MenuItem iconStart={<RiShareBoxLine />}>Share</MenuItem>
+        <MenuItem iconStart={<RiChat1Line />}>Feedback</MenuItem>
+        <MenuSeparator />
+        <SubmenuTrigger>
+          <MenuItem iconStart={<RiSettingsLine />}>Settings</MenuItem>
+          <Menu placement="right top">
+            <MenuItem>Edit</MenuItem>
+            <MenuItem>Duplicate</MenuItem>
+            <MenuItem>Rename</MenuItem>
+          </Menu>
+        </SubmenuTrigger>
       </Menu>
     </MenuTrigger>
   </MemoryRouter>
@@ -53,9 +71,9 @@ export const PreviewIcons = () => (
     <MenuTrigger>
       <Button variant="secondary">Menu</Button>
       <Menu>
-        <MenuItem icon={<RiFileLine />}>New File</MenuItem>
-        <MenuItem icon={<RiFolderLine />}>New Folder</MenuItem>
-        <MenuItem icon={<RiImageLine />}>New Image</MenuItem>
+        <MenuItem iconStart={<RiFileLine />}>New File</MenuItem>
+        <MenuItem iconStart={<RiFolderLine />}>New Folder</MenuItem>
+        <MenuItem iconStart={<RiImageLine />}>New Image</MenuItem>
       </Menu>
     </MenuTrigger>
   </MemoryRouter>
@@ -110,7 +128,7 @@ export const PreviewSeparators = () => (
 
 export const PreviewAutocompleteMenu = () => (
   <MemoryRouter>
-    <MenuAutocomplete label="Search" placeholder="Type to search...">
+    <MenuAutocomplete placeholder="Type to search...">
       <MenuItem>Option 1</MenuItem>
       <MenuItem>Option 2</MenuItem>
       <MenuItem>Option 3</MenuItem>
@@ -120,7 +138,7 @@ export const PreviewAutocompleteMenu = () => (
 
 export const PreviewAutocompleteListbox = () => (
   <MemoryRouter>
-    <MenuAutocomplete label="Select an option" placeholder="Type to filter...">
+    <MenuAutocomplete placeholder="Type to filter...">
       <MenuListBoxItem>Option 1</MenuListBoxItem>
       <MenuListBoxItem>Option 2</MenuListBoxItem>
       <MenuListBoxItem>Option 3</MenuListBoxItem>
@@ -130,11 +148,7 @@ export const PreviewAutocompleteListbox = () => (
 
 export const PreviewAutocompleteListboxMultiple = () => (
   <MemoryRouter>
-    <MenuAutocomplete
-      label="Select multiple options"
-      placeholder="Type to filter..."
-      selectionMode="multiple"
-    >
+    <MenuAutocomplete placeholder="Type to filter..." selectionMode="multiple">
       <MenuListBoxItem>Option 1</MenuListBoxItem>
       <MenuListBoxItem>Option 2</MenuListBoxItem>
       <MenuListBoxItem>Option 3</MenuListBoxItem>
diff --git a/docs-ui/src/app/components/search-field/components.tsx b/docs-ui/src/app/components/search-field/components.tsx
index 753f6ecd73..33a6ba3540 100644
--- a/docs-ui/src/app/components/search-field/components.tsx
+++ b/docs-ui/src/app/components/search-field/components.tsx
@@ -2,10 +2,16 @@
 
 import { SearchField } from '../../../../../packages/ui/src/components/SearchField/SearchField';
 import { Flex } from '../../../../../packages/ui/src/components/Flex/Flex';
-import { RiEBike2Line } from '@remixicon/react';
 
 export const WithLabel = () => {
-  return <SearchField name="url" label="Label" aria-label="Search" />;
+  return (
+    <SearchField
+      name="url"
+      label="Label"
+      aria-label="Search"
+      style={{ width: '100%', maxWidth: '300px' }}
+    />
+  );
 };
 
 export const Sizes = () => {
@@ -24,6 +30,7 @@ export const WithDescription = () => {
       label="Label"
       description="Description"
       aria-label="Search"
+      style={{ width: '100%', maxWidth: '300px' }}
     />
   );
 };
@@ -45,7 +52,6 @@ export const StartCollapsed = () => {
           startCollapsed
         />
       </Flex>
-      <SearchField name="url" aria-label="Search" size="small" startCollapsed />
     </Flex>
   );
 };
diff --git a/docs-ui/src/app/components/table/components.tsx b/docs-ui/src/app/components/table/components.tsx
index 8850d3a214..cb158579a1 100644
--- a/docs-ui/src/app/components/table/components.tsx
+++ b/docs-ui/src/app/components/table/components.tsx
@@ -1,163 +1,188 @@
 'use client';
 
-import dynamic from 'next/dynamic';
-
-// Import Table components dynamically with ssr: false to avoid SSR issues
-const TableComponents = dynamic(
-  () =>
-    import('../../../../../packages/ui/src/components/Table').then(mod => ({
-      default: () => null, // Placeholder
-      Table: mod.Table,
-      TableHeader: mod.TableHeader,
-      Column: mod.Column,
-      TableBody: mod.TableBody,
-      Row: mod.Row,
-      Cell: mod.Cell,
-    })),
-  { ssr: false },
-);
-
 import {
   Table,
-  TableHeader,
-  Column,
-  TableBody,
-  Row,
-  Cell,
+  CellProfile,
+  CellText,
+  type ColumnConfig,
+  useTable,
 } from '../../../../../packages/ui/src/components/Table';
+import { Flex } from '../../../../../packages/ui/src/components/Flex/Flex';
+import { Text } from '../../../../../packages/ui/src/components/Text/Text';
+import { RadioGroup } from '../../../../../packages/ui/src/components/RadioGroup/RadioGroup';
+import { Radio } from '../../../../../packages/ui/src/components/RadioGroup';
+import { data as data4 } from '../../../../../packages/ui/src/components/Table/stories/mocked-data4';
 import { useState } from 'react';
-import type { Selection } from 'react-aria-components';
+import {
+  selectionData,
+  selectionColumns,
+} from '../../../../../packages/ui/src/components/Table/stories/utils';
+import { MemoryRouter } from 'react-router-dom';
 
-const rockBands = [
-  { id: 1, name: 'The Beatles', genre: 'Rock', year: 1960 },
-  { id: 2, name: 'Led Zeppelin', genre: 'Hard Rock', year: 1968 },
-  { id: 3, name: 'Pink Floyd', genre: 'Progressive Rock', year: 1965 },
-  { id: 4, name: 'The Rolling Stones', genre: 'Rock', year: 1962 },
-  { id: 5, name: 'Queen', genre: 'Rock', year: 1970 },
+type Data4Item = (typeof data4)[0];
+
+const columns: ColumnConfig<Data4Item>[] = [
+  {
+    id: 'name',
+    label: 'Band name',
+    isRowHeader: true,
+    cell: item => (
+      <CellProfile name={item.name} src={item.image} href={item.website} />
+    ),
+  },
+  {
+    id: 'genre',
+    label: 'Genre',
+    cell: item => <CellText title={item.genre} />,
+  },
+  {
+    id: 'yearFormed',
+    label: 'Year formed',
+    cell: item => <CellText title={item.yearFormed.toString()} />,
+  },
+  {
+    id: 'albums',
+    label: 'Albums',
+    cell: item => <CellText title={item.albums.toString()} />,
+  },
 ];
 
-// Simple wrapper to ensure client-side only rendering
-const ClientOnly = ({ children }: { children: React.ReactNode }) => {
-  const [mounted, setMounted] = useState(false);
-
-  useState(() => {
-    if (typeof window !== 'undefined') {
-      setMounted(true);
-    }
+export const TableRockBand = () => {
+  const { tableProps } = useTable({
+    mode: 'complete',
+    getData: () => data4,
+    paginationOptions: { pageSize: 5 },
   });
 
-  if (!mounted) return <div>Loading...</div>;
-  return <>{children}</>;
-};
-
-export const TableRockBand = () => (
-  <ClientOnly>
-    <Table aria-label="Rock Bands">
-      <TableHeader>
-        <Column>Name</Column>
-        <Column>Genre</Column>
-        <Column>Year</Column>
-      </TableHeader>
-      <TableBody>
-        {rockBands.map(band => (
-          <Row key={band.id}>
-            <Cell>{band.name}</Cell>
-            <Cell>{band.genre}</Cell>
-            <Cell>{band.year}</Cell>
-          </Row>
-        ))}
-      </TableBody>
-    </Table>
-  </ClientOnly>
-);
-
-export const SelectionModePlayground = () => {
-  const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set());
-
   return (
-    <ClientOnly>
-      <Table
-        aria-label="Rock Bands"
-        selectionMode="multiple"
-        selectedKeys={selectedKeys}
-        onSelectionChange={setSelectedKeys}
-      >
-        <TableHeader>
-          <Column>Name</Column>
-          <Column>Genre</Column>
-          <Column>Year</Column>
-        </TableHeader>
-        <TableBody>
-          {rockBands.map(band => (
-            <Row key={band.id}>
-              <Cell>{band.name}</Cell>
-              <Cell>{band.genre}</Cell>
-              <Cell>{band.year}</Cell>
-            </Row>
-          ))}
-        </TableBody>
-      </Table>
-    </ClientOnly>
-  );
-};
-
-export const SelectionBehaviorPlayground = () => {
-  const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set());
-
-  return (
-    <ClientOnly>
-      <Table
-        aria-label="Rock Bands"
-        selectionMode="multiple"
-        selectionBehavior="replace"
-        selectedKeys={selectedKeys}
-        onSelectionChange={setSelectedKeys}
-      >
-        <TableHeader>
-          <Column>Name</Column>
-          <Column>Genre</Column>
-          <Column>Year</Column>
-        </TableHeader>
-        <TableBody>
-          {rockBands.map(band => (
-            <Row key={band.id}>
-              <Cell>{band.name}</Cell>
-              <Cell>{band.genre}</Cell>
-              <Cell>{band.year}</Cell>
-            </Row>
-          ))}
-        </TableBody>
-      </Table>
-    </ClientOnly>
+    <MemoryRouter>
+      <Table columnConfig={columns} {...tableProps} />
+    </MemoryRouter>
   );
 };
 
 export const SelectionToggleWithActions = () => {
-  const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set());
+  const [selected, setSelected] = useState<Set<string | number> | 'all'>(
+    new Set(),
+  );
+
+  const { tableProps } = useTable({
+    mode: 'complete',
+    getData: () => selectionData,
+    paginationOptions: { pageSize: 10 },
+  });
 
   return (
-    <ClientOnly>
+    <MemoryRouter>
       <Table
-        aria-label="Rock Bands"
-        selectionMode="multiple"
-        selectedKeys={selectedKeys}
-        onSelectionChange={setSelectedKeys}
-      >
-        <TableHeader>
-          <Column>Name</Column>
-          <Column>Genre</Column>
-          <Column>Year</Column>
-        </TableHeader>
-        <TableBody>
-          {rockBands.map(band => (
-            <Row key={band.id}>
-              <Cell>{band.name}</Cell>
-              <Cell>{band.genre}</Cell>
-              <Cell>{band.year}</Cell>
-            </Row>
-          ))}
-        </TableBody>
-      </Table>
-    </ClientOnly>
+        {...tableProps}
+        columnConfig={selectionColumns}
+        selection={{
+          mode: 'multiple',
+          behavior: 'toggle',
+          selected,
+          onSelectionChange: setSelected,
+        }}
+        rowConfig={{ onClick: item => alert(`Clicked: ${item.name}`) }}
+      />
+    </MemoryRouter>
+  );
+};
+
+export const SelectionModePlayground = () => {
+  const [selectionMode, setSelectionMode] = useState<'single' | 'multiple'>(
+    'multiple',
+  );
+  const [selected, setSelected] = useState<Set<string | number> | 'all'>(
+    new Set(),
+  );
+
+  const { tableProps } = useTable({
+    mode: 'complete',
+    getData: () => selectionData,
+    paginationOptions: { pageSize: 10 },
+  });
+
+  return (
+    <MemoryRouter>
+      <Flex direction="column" gap="8">
+        <Table
+          {...tableProps}
+          columnConfig={selectionColumns}
+          selection={{
+            mode: selectionMode,
+            behavior: 'toggle',
+            selected,
+            onSelectionChange: setSelected,
+          }}
+        />
+        <div>
+          <Text as="h4" style={{ marginBottom: 'var(--bui-space-2)' }}>
+            Selection mode:
+          </Text>
+          <RadioGroup
+            aria-label="Selection mode"
+            orientation="horizontal"
+            value={selectionMode}
+            onChange={value => {
+              setSelectionMode(value as 'single' | 'multiple');
+              setSelected(new Set());
+            }}
+          >
+            <Radio value="single">single</Radio>
+            <Radio value="multiple">multiple</Radio>
+          </RadioGroup>
+        </div>
+      </Flex>
+    </MemoryRouter>
+  );
+};
+
+export const SelectionBehaviorPlayground = () => {
+  const [selectionBehavior, setSelectionBehavior] = useState<
+    'toggle' | 'replace'
+  >('toggle');
+  const [selected, setSelected] = useState<Set<string | number> | 'all'>(
+    new Set(),
+  );
+
+  const { tableProps } = useTable({
+    mode: 'complete',
+    getData: () => selectionData,
+    paginationOptions: { pageSize: 10 },
+  });
+
+  return (
+    <MemoryRouter>
+      <Flex direction="column" gap="8">
+        <Table
+          {...tableProps}
+          columnConfig={selectionColumns}
+          selection={{
+            mode: 'multiple',
+            behavior: selectionBehavior,
+            selected,
+            onSelectionChange: setSelected,
+          }}
+        />
+        <div>
+          <Text as="h4" style={{ marginBottom: 'var(--bui-space-2)' }}>
+            Selection behavior:
+          </Text>
+          <RadioGroup
+            aria-label="Selection behavior"
+            orientation="horizontal"
+            value={selectionBehavior}
+            onChange={value => {
+              setSelectionBehavior(value as 'toggle' | 'replace');
+              setSelected(new Set());
+            }}
+          >
+            <Radio value="toggle">toggle</Radio>
+            <Radio value="replace">replace</Radio>
+          </RadioGroup>
+        </div>
+      </Flex>
+    </MemoryRouter>
   );
 };
diff --git a/docs-ui/src/app/components/toggle-button-group/components.tsx b/docs-ui/src/app/components/toggle-button-group/components.tsx
index 0812f5d3a5..a6da51f862 100644
--- a/docs-ui/src/app/components/toggle-button-group/components.tsx
+++ b/docs-ui/src/app/components/toggle-button-group/components.tsx
@@ -2,78 +2,153 @@
 
 import { ToggleButtonGroup } from '../../../../../packages/ui/src/components/ToggleButtonGroup/ToggleButtonGroup';
 import { ToggleButton } from '../../../../../packages/ui/src/components/ToggleButton/ToggleButton';
-import { RiBold, RiItalic, RiUnderline } from '@remixicon/react';
-import { useState } from 'react';
+import { Flex } from '../../../../../packages/ui/src/components/Flex/Flex';
+import { Text } from '../../../../../packages/ui/src/components/Text/Text';
+import {
+  RiCloudLine,
+  RiStarFill,
+  RiStarLine,
+  RiArrowRightSLine,
+} from '@remixicon/react';
 
-export const Default = () => {
-  const [selected, setSelected] = useState<string[]>([]);
-  return (
-    <ToggleButtonGroup
-      selectionMode="multiple"
-      selectedKeys={selected}
-      onSelectionChange={keys => setSelected(Array.from(keys as Set<string>))}
-    >
-      <ToggleButton id="bold" icon={<RiBold />} />
-      <ToggleButton id="italic" icon={<RiItalic />} />
-      <ToggleButton id="underline" icon={<RiUnderline />} />
-    </ToggleButtonGroup>
-  );
-};
+export const ToggleButtonGroupSurfaces = () => (
+  <Flex direction="column" gap="4">
+    <Flex direction="column" gap="4">
+      <Text>Default</Text>
+      <Flex align="center" p="4" gap="4">
+        <ToggleButtonGroup
+          selectionMode="single"
+          defaultSelectedKeys={['option1']}
+        >
+          <ToggleButton id="option1">Option 1</ToggleButton>
+          <ToggleButton id="option2">Option 2</ToggleButton>
+          <ToggleButton id="option3">Option 3</ToggleButton>
+        </ToggleButtonGroup>
+      </Flex>
+    </Flex>
+    <Flex direction="column" gap="4">
+      <Text>On Surface 0</Text>
+      <Flex align="center" surface="0" p="4" gap="4">
+        <ToggleButtonGroup
+          selectionMode="single"
+          defaultSelectedKeys={['option1']}
+        >
+          <ToggleButton id="option1">Option 1</ToggleButton>
+          <ToggleButton id="option2">Option 2</ToggleButton>
+          <ToggleButton id="option3">Option 3</ToggleButton>
+        </ToggleButtonGroup>
+      </Flex>
+    </Flex>
+    <Flex direction="column" gap="4">
+      <Text>On Surface 1</Text>
+      <Flex align="center" surface="1" p="4" gap="4">
+        <ToggleButtonGroup
+          selectionMode="single"
+          defaultSelectedKeys={['option1']}
+        >
+          <ToggleButton id="option1">Option 1</ToggleButton>
+          <ToggleButton id="option2">Option 2</ToggleButton>
+          <ToggleButton id="option3">Option 3</ToggleButton>
+        </ToggleButtonGroup>
+      </Flex>
+    </Flex>
+    <Flex direction="column" gap="4">
+      <Text>On Surface 2</Text>
+      <Flex align="center" surface="2" p="4" gap="4">
+        <ToggleButtonGroup
+          selectionMode="single"
+          defaultSelectedKeys={['option1']}
+        >
+          <ToggleButton id="option1">Option 1</ToggleButton>
+          <ToggleButton id="option2">Option 2</ToggleButton>
+          <ToggleButton id="option3">Option 3</ToggleButton>
+        </ToggleButtonGroup>
+      </Flex>
+    </Flex>
+    <Flex direction="column" gap="4">
+      <Text>On Surface 3</Text>
+      <Flex align="center" surface="3" p="4" gap="4">
+        <ToggleButtonGroup
+          selectionMode="single"
+          defaultSelectedKeys={['option1']}
+        >
+          <ToggleButton id="option1">Option 1</ToggleButton>
+          <ToggleButton id="option2">Option 2</ToggleButton>
+          <ToggleButton id="option3">Option 3</ToggleButton>
+        </ToggleButtonGroup>
+      </Flex>
+    </Flex>
+  </Flex>
+);
 
-export const SingleSelection = () => {
-  const [selected, setSelected] = useState<string>('left');
-  return (
-    <ToggleButtonGroup
-      selectionMode="single"
-      selectedKeys={[selected]}
-      onSelectionChange={keys => {
-        const key = Array.from(keys as Set<string>)[0];
-        if (key) setSelected(key);
-      }}
-    >
-      <ToggleButton id="left">Left</ToggleButton>
-      <ToggleButton id="center">Center</ToggleButton>
-      <ToggleButton id="right">Right</ToggleButton>
-    </ToggleButtonGroup>
-  );
-};
+export const ToggleButtonGroupSingle = () => (
+  <ToggleButtonGroup selectionMode="single" defaultSelectedKeys={['dogs']}>
+    <ToggleButton id="dogs">Dogs</ToggleButton>
+    <ToggleButton id="cat">Cats</ToggleButton>
+    <ToggleButton id="bird">Birds</ToggleButton>
+  </ToggleButtonGroup>
+);
 
-export const Sizes = () => {
-  const [small, setSmall] = useState<string[]>([]);
-  const [medium, setMedium] = useState<string[]>([]);
+export const ToggleButtonGroupMultiple = () => (
+  <ToggleButtonGroup
+    selectionMode="multiple"
+    defaultSelectedKeys={['frontend']}
+  >
+    <ToggleButton id="frontend">Frontend</ToggleButton>
+    <ToggleButton id="backend">Backend</ToggleButton>
+    <ToggleButton id="platform">Platform</ToggleButton>
+  </ToggleButtonGroup>
+);
 
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
-      <ToggleButtonGroup
-        size="small"
-        selectionMode="multiple"
-        selectedKeys={small}
-        onSelectionChange={keys => setSmall(Array.from(keys as Set<string>))}
-      >
-        <ToggleButton id="bold" icon={<RiBold />} />
-        <ToggleButton id="italic" icon={<RiItalic />} />
-        <ToggleButton id="underline" icon={<RiUnderline />} />
-      </ToggleButtonGroup>
-      <ToggleButtonGroup
-        size="medium"
-        selectionMode="multiple"
-        selectedKeys={medium}
-        onSelectionChange={keys => setMedium(Array.from(keys as Set<string>))}
-      >
-        <ToggleButton id="bold" icon={<RiBold />} />
-        <ToggleButton id="italic" icon={<RiItalic />} />
-        <ToggleButton id="underline" icon={<RiUnderline />} />
-      </ToggleButtonGroup>
-    </div>
-  );
-};
+export const ToggleButtonGroupVertical = () => (
+  <ToggleButtonGroup selectionMode="single" orientation="vertical">
+    <ToggleButton id="morning">Morning</ToggleButton>
+    <ToggleButton id="afternoon">Afternoon</ToggleButton>
+    <ToggleButton id="evening">Evening</ToggleButton>
+  </ToggleButtonGroup>
+);
 
-export const Disabled = () => {
-  return (
-    <ToggleButtonGroup isDisabled selectionMode="multiple">
-      <ToggleButton id="bold" icon={<RiBold />} />
-      <ToggleButton id="italic" icon={<RiItalic />} />
-      <ToggleButton id="underline" icon={<RiUnderline />} />
-    </ToggleButtonGroup>
-  );
-};
+export const ToggleButtonGroupDisabled = () => (
+  <ToggleButtonGroup selectionMode="single" isDisabled>
+    <ToggleButton id="cat">Cat</ToggleButton>
+    <ToggleButton id="dog">Dog</ToggleButton>
+    <ToggleButton id="bird">Bird</ToggleButton>
+  </ToggleButtonGroup>
+);
+
+export const ToggleButtonGroupDisallowEmpty = () => (
+  <ToggleButtonGroup
+    selectionMode="single"
+    disallowEmptySelection
+    defaultSelectedKeys={['one']}
+  >
+    <ToggleButton id="one">One</ToggleButton>
+    <ToggleButton id="two">Two</ToggleButton>
+    <ToggleButton id="three">Three</ToggleButton>
+  </ToggleButtonGroup>
+);
+
+export const ToggleButtonGroupIcons = () => (
+  <ToggleButtonGroup selectionMode="multiple" defaultSelectedKeys={['cloud']}>
+    <ToggleButton id="cloud" aria-label="Cloud" iconStart={<RiCloudLine />} />
+    <ToggleButton
+      id="starred"
+      aria-label="Starred"
+      iconStart={<RiStarFill />}
+    />
+    <ToggleButton id="star" iconStart={<RiStarLine />}>
+      Star
+    </ToggleButton>
+    <ToggleButton id="next" iconEnd={<RiArrowRightSLine />}>
+      Next
+    </ToggleButton>
+  </ToggleButtonGroup>
+);
+
+export const ToggleButtonGroupIconsOnly = () => (
+  <ToggleButtonGroup selectionMode="multiple" defaultSelectedKeys={['cloud']}>
+    <ToggleButton id="cloud" aria-label="Cloud" iconStart={<RiCloudLine />} />
+    <ToggleButton id="star" aria-label="Star" iconStart={<RiStarLine />} />
+    <ToggleButton id="next" aria-label="Next" iconEnd={<RiArrowRightSLine />} />
+  </ToggleButtonGroup>
+);
diff --git a/docs-ui/src/app/components/toggle-button-group/page.mdx b/docs-ui/src/app/components/toggle-button-group/page.mdx
index 47fb4174a1..4742fff9a5 100644
--- a/docs-ui/src/app/components/toggle-button-group/page.mdx
+++ b/docs-ui/src/app/components/toggle-button-group/page.mdx
@@ -4,12 +4,25 @@ import { CodeBlock } from '@/components/CodeBlock';
 import { toggleButtonGroupPropDefs } from './props-definition';
 import {
   toggleButtonGroupUsageSnippet,
-  defaultSnippet,
-  singleSelectionSnippet,
-  sizesSnippet,
-  disabledSnippet,
+  toggleButtonGroupSurfacesSnippet,
+  toggleButtonGroupSingleSnippet,
+  toggleButtonGroupMultipleSnippet,
+  toggleButtonGroupIconsSnippet,
+  toggleButtonGroupIconsOnlySnippet,
+  toggleButtonGroupDisallowEmptySnippet,
+  toggleButtonGroupVerticalSnippet,
+  toggleButtonGroupDisabledSnippet,
 } from './snippets';
-import { Default, SingleSelection, Sizes, Disabled } from './components';
+import {
+  ToggleButtonGroupSingle,
+  ToggleButtonGroupMultiple,
+  ToggleButtonGroupVertical,
+  ToggleButtonGroupDisabled,
+  ToggleButtonGroupDisallowEmpty,
+  ToggleButtonGroupIcons,
+  ToggleButtonGroupIconsOnly,
+  ToggleButtonGroupSurfaces,
+} from './components';
 import { PageTitle } from '@/components/PageTitle';
 import { Theming } from '@/components/Theming';
 import { ChangelogComponent } from '@/components/ChangelogComponent';
@@ -20,7 +33,12 @@ import { ToggleButtonGroupDefinition } from '../../../utils/definitions';
   description="A grouping container for related [ToggleButtons](./toggle-button) supporting single or multiple selection."
 />
 
-<Snippet align="center" py={4} preview={<Default />} code={defaultSnippet} />
+<Snippet
+  align="center"
+  py={4}
+  preview={<ToggleButtonGroupSingle />}
+  code={toggleButtonGroupUsageSnippet}
+/>
 
 ## Usage
 
@@ -32,24 +50,74 @@ import { ToggleButtonGroupDefinition } from '../../../utils/definitions';
 
 ## Examples
 
+### Surfaces
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  preview={<ToggleButtonGroupSurfaces />}
+  code={toggleButtonGroupSurfacesSnippet}
+/>
+
 ### Single Selection
 
 <Snippet
   align="center"
   py={4}
   open
-  preview={<SingleSelection />}
-  code={singleSelectionSnippet}
+  preview={<ToggleButtonGroupSingle />}
+  code={toggleButtonGroupSingleSnippet}
 />
 
-### Sizes
+### Multiple Selection
 
 <Snippet
   align="center"
   py={4}
   open
-  preview={<Sizes />}
-  code={sizesSnippet}
+  preview={<ToggleButtonGroupMultiple />}
+  code={toggleButtonGroupMultipleSnippet}
+/>
+
+### Icons and Text
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  preview={<ToggleButtonGroupIcons />}
+  code={toggleButtonGroupIconsSnippet}
+/>
+
+### Icons Only
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  preview={<ToggleButtonGroupIconsOnly />}
+  code={toggleButtonGroupIconsOnlySnippet}
+/>
+
+### Disallow Empty Selection
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  preview={<ToggleButtonGroupDisallowEmpty />}
+  code={toggleButtonGroupDisallowEmptySnippet}
+/>
+
+### Vertical Orientation
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  preview={<ToggleButtonGroupVertical />}
+  code={toggleButtonGroupVerticalSnippet}
 />
 
 ### Disabled
@@ -58,8 +126,8 @@ import { ToggleButtonGroupDefinition } from '../../../utils/definitions';
   align="center"
   py={4}
   open
-  preview={<Disabled />}
-  code={disabledSnippet}
+  preview={<ToggleButtonGroupDisabled />}
+  code={toggleButtonGroupDisabledSnippet}
 />
 
 <Theming definition={ToggleButtonGroupDefinition} />
diff --git a/docs-ui/src/app/components/toggle-button-group/snippets.ts b/docs-ui/src/app/components/toggle-button-group/snippets.ts
index 4cf3eff70e..099891dbae 100644
--- a/docs-ui/src/app/components/toggle-button-group/snippets.ts
+++ b/docs-ui/src/app/components/toggle-button-group/snippets.ts
@@ -1,59 +1,115 @@
 export const toggleButtonGroupUsageSnippet = `import { ToggleButtonGroup, ToggleButton } from '@backstage/ui';
-import { useState } from 'react';
 
-const [selected, setSelected] = useState<string[]>([]);
-
-<ToggleButtonGroup
-  selectionMode="multiple"
-  selectedKeys={selected}
-  onSelectionChange={(keys) => setSelected(Array.from(keys))}
->
-  <ToggleButton id="bold" icon={<RiBold />} />
-  <ToggleButton id="italic" icon={<RiItalic />} />
-  <ToggleButton id="underline" icon={<RiUnderline />} />
+<ToggleButtonGroup selectionMode="single">
+  <ToggleButton id="dogs">Dogs</ToggleButton>
+  <ToggleButton id="cats">Cats</ToggleButton>
+  <ToggleButton id="birds">Birds</ToggleButton>
 </ToggleButtonGroup>`;
 
-export const defaultSnippet = `const [selected, setSelected] = useState<string[]>([]);
-
-<ToggleButtonGroup
-  selectionMode="multiple"
-  selectedKeys={selected}
-  onSelectionChange={(keys) => setSelected(Array.from(keys))}
->
-  <ToggleButton id="bold" icon={<RiBold />} />
-  <ToggleButton id="italic" icon={<RiItalic />} />
-  <ToggleButton id="underline" icon={<RiUnderline />} />
+export const toggleButtonGroupSingleSnippet = `<ToggleButtonGroup selectionMode="single" defaultSelectedKeys={['dogs']}>
+  <ToggleButton id="dogs">Dogs</ToggleButton>
+  <ToggleButton id="cat">Cats</ToggleButton>
+  <ToggleButton id="bird">Birds</ToggleButton>
 </ToggleButtonGroup>`;
 
-export const singleSelectionSnippet = `const [selected, setSelected] = useState<string>('left');
-
-<ToggleButtonGroup
-  selectionMode="single"
-  selectedKeys={[selected]}
-  onSelectionChange={(keys) => {
-    const key = Array.from(keys)[0];
-    if (key) setSelected(key);
-  }}
->
-  <ToggleButton id="left">Left</ToggleButton>
-  <ToggleButton id="center">Center</ToggleButton>
-  <ToggleButton id="right">Right</ToggleButton>
+export const toggleButtonGroupMultipleSnippet = `<ToggleButtonGroup selectionMode="multiple" defaultSelectedKeys={['frontend']}>
+  <ToggleButton id="frontend">Frontend</ToggleButton>
+  <ToggleButton id="backend">Backend</ToggleButton>
+  <ToggleButton id="platform">Platform</ToggleButton>
 </ToggleButtonGroup>`;
 
-export const sizesSnippet = `<ToggleButtonGroup size="small" selectionMode="multiple">
-  <ToggleButton id="bold" icon={<RiBold />} />
-  <ToggleButton id="italic" icon={<RiItalic />} />
-  <ToggleButton id="underline" icon={<RiUnderline />} />
-</ToggleButtonGroup>
-
-<ToggleButtonGroup size="medium" selectionMode="multiple">
-  <ToggleButton id="bold" icon={<RiBold />} />
-  <ToggleButton id="italic" icon={<RiItalic />} />
-  <ToggleButton id="underline" icon={<RiUnderline />} />
+export const toggleButtonGroupVerticalSnippet = `<ToggleButtonGroup selectionMode="single" orientation="vertical">
+  <ToggleButton id="morning">Morning</ToggleButton>
+  <ToggleButton id="afternoon">Afternoon</ToggleButton>
+  <ToggleButton id="evening">Evening</ToggleButton>
 </ToggleButtonGroup>`;
 
-export const disabledSnippet = `<ToggleButtonGroup isDisabled selectionMode="multiple">
-  <ToggleButton id="bold" icon={<RiBold />} />
-  <ToggleButton id="italic" icon={<RiItalic />} />
-  <ToggleButton id="underline" icon={<RiUnderline />} />
+export const toggleButtonGroupDisabledSnippet = `<ToggleButtonGroup selectionMode="single" isDisabled>
+  <ToggleButton id="cat">Cat</ToggleButton>
+  <ToggleButton id="dog">Dog</ToggleButton>
+  <ToggleButton id="bird">Bird</ToggleButton>
 </ToggleButtonGroup>`;
+
+export const toggleButtonGroupDisallowEmptySnippet = `<ToggleButtonGroup selectionMode="single" disallowEmptySelection defaultSelectedKeys={['one']}>
+  <ToggleButton id="one">One</ToggleButton>
+  <ToggleButton id="two">Two</ToggleButton>
+  <ToggleButton id="three">Three</ToggleButton>
+</ToggleButtonGroup>`;
+
+export const toggleButtonGroupIconsSnippet = `import { RiCloudLine, RiStarFill, RiStarLine, RiArrowRightSLine } from '@remixicon/react';
+
+<ToggleButtonGroup selectionMode="multiple" defaultSelectedKeys={['cloud']}>
+  <ToggleButton id="cloud" aria-label="Cloud" iconStart={<RiCloudLine />} />
+  <ToggleButton
+    id="starred"
+    aria-label="Starred"
+    iconStart={<RiStarFill />}
+  />
+  <ToggleButton id="star" iconStart={<RiStarLine />}>
+    Star
+  </ToggleButton>
+  <ToggleButton id="next" iconEnd={<RiArrowRightSLine />}>
+    Next
+  </ToggleButton>
+</ToggleButtonGroup>`;
+
+export const toggleButtonGroupIconsOnlySnippet = `import { RiCloudLine, RiStarLine, RiArrowRightSLine } from '@remixicon/react';
+
+<ToggleButtonGroup selectionMode="multiple" defaultSelectedKeys={['cloud']}>
+  <ToggleButton id="cloud" iconStart={<RiCloudLine />} />
+  <ToggleButton id="star" iconStart={<RiStarLine />} />
+  <ToggleButton id="next" iconEnd={<RiArrowRightSLine />} />
+</ToggleButtonGroup>`;
+
+export const toggleButtonGroupSurfacesSnippet = `<Flex direction="column" gap="4">
+  <Flex direction="column" gap="4">
+    <Text>Default</Text>
+    <Flex align="center" p="4" gap="4">
+      <ToggleButtonGroup selectionMode="single" defaultSelectedKeys={['option1']}>
+        <ToggleButton id="option1">Option 1</ToggleButton>
+        <ToggleButton id="option2">Option 2</ToggleButton>
+        <ToggleButton id="option3">Option 3</ToggleButton>
+      </ToggleButtonGroup>
+    </Flex>
+  </Flex>
+  <Flex direction="column" gap="4">
+    <Text>On Surface 0</Text>
+    <Flex align="center" surface="0" p="4" gap="4">
+      <ToggleButtonGroup selectionMode="single" defaultSelectedKeys={['option1']}>
+        <ToggleButton id="option1">Option 1</ToggleButton>
+        <ToggleButton id="option2">Option 2</ToggleButton>
+        <ToggleButton id="option3">Option 3</ToggleButton>
+      </ToggleButtonGroup>
+    </Flex>
+  </Flex>
+  <Flex direction="column" gap="4">
+    <Text>On Surface 1</Text>
+    <Flex align="center" surface="1" p="4" gap="4">
+      <ToggleButtonGroup selectionMode="single" defaultSelectedKeys={['option1']}>
+        <ToggleButton id="option1">Option 1</ToggleButton>
+        <ToggleButton id="option2">Option 2</ToggleButton>
+        <ToggleButton id="option3">Option 3</ToggleButton>
+      </ToggleButtonGroup>
+    </Flex>
+  </Flex>
+  <Flex direction="column" gap="4">
+    <Text>On Surface 2</Text>
+    <Flex align="center" surface="2" p="4" gap="4">
+      <ToggleButtonGroup selectionMode="single" defaultSelectedKeys={['option1']}>
+        <ToggleButton id="option1">Option 1</ToggleButton>
+        <ToggleButton id="option2">Option 2</ToggleButton>
+        <ToggleButton id="option3">Option 3</ToggleButton>
+      </ToggleButtonGroup>
+    </Flex>
+  </Flex>
+  <Flex direction="column" gap="4">
+    <Text>On Surface 3</Text>
+    <Flex align="center" surface="3" p="4" gap="4">
+      <ToggleButtonGroup selectionMode="single" defaultSelectedKeys={['option1']}>
+        <ToggleButton id="option1">Option 1</ToggleButton>
+        <ToggleButton id="option2">Option 2</ToggleButton>
+        <ToggleButton id="option3">Option 3</ToggleButton>
+      </ToggleButtonGroup>
+    </Flex>
+  </Flex>
+</Flex>`;
diff --git a/docs-ui/src/app/components/toggle-button/components.tsx b/docs-ui/src/app/components/toggle-button/components.tsx
index 017af4eee1..6fa5aada98 100644
--- a/docs-ui/src/app/components/toggle-button/components.tsx
+++ b/docs-ui/src/app/components/toggle-button/components.tsx
@@ -20,7 +20,7 @@ export const WithIcon = () => {
     <ToggleButton
       isSelected={isSelected}
       onChange={setIsSelected}
-      icon={<RiCheckLine />}
+      iconStart={<RiCheckLine />}
     >
       With Icon
     </ToggleButton>