Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve ToggleButton docs page and block examples (#1610)

Kenton Quatman5342f1279e75
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupMultiple.doc.mjs b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupMultiple.doc.mjs
deleted file mode 100644
index b242dafabc..0000000000
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupMultiple.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'ToggleButton — Multi-Select Group',
- description:
- 'Multi-select toggle button group forming a text formatting toolbar with bold, italic, and underline.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ToggleButton', 'ToggleButtonGroup'],
-};
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupMultiple.tsx b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupMultiple.tsx
deleted file mode 100644
index 62b36ffb7e..0000000000
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupMultiple.tsx
+++ /dev/null
@@ -1,55 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSToggleButton, XDSToggleButtonGroup} from '@xds/core/ToggleButton';
-
-const iconSize = {width: 16, height: 16} as const;
-const svgProps = {viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round' as const, strokeLinejoin: 'round' as const, ...iconSize};
-
-const BoldIcon = (
- <svg {...svgProps}>
- <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6zM6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
- </svg>
-);
-
-const ItalicIcon = (
- <svg {...svgProps}>
- <path d="M10 4h4M14 20h-4M15 4l-6 16" />
- </svg>
-);
-
-const UnderlineIcon = (
- <svg {...svgProps}>
- <path d="M7 4v7a5 5 0 0 0 10 0V4M5 21h14" />
- </svg>
-);
-
-export default function ToggleButtonGroupMultiple() {
- const [formats, setFormats] = useState<string[]>([]);
- return (
- <XDSToggleButtonGroup
- type="multiple"
- value={formats}
- onChange={setFormats}
- label="Text formatting">
- <XDSToggleButton
- value="bold"
- label="Bold"
- icon={BoldIcon}
- isIconOnly
- />
- <XDSToggleButton
- value="italic"
- label="Italic"
- icon={ItalicIcon}
- isIconOnly
- />
- <XDSToggleButton
- value="underline"
- label="Underline"
- icon={UnderlineIcon}
- isIconOnly
- />
- </XDSToggleButtonGroup>
- );
-}
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupSingle.doc.mjs b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupSingle.doc.mjs
deleted file mode 100644
index 465b69a218..0000000000
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupSingle.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'ToggleButton — Single-Select Group',
- description:
- 'Single-select toggle button group acting as a view mode switcher between list and grid.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ToggleButton', 'ToggleButtonGroup'],
-};
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupSingle.tsx b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupSingle.tsx
deleted file mode 100644
index 6d8ebbfa8c..0000000000
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonGroupSingle.tsx
+++ /dev/null
@@ -1,39 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSToggleButton, XDSToggleButtonGroup} from '@xds/core/ToggleButton';
-
-const iconSize = {width: 16, height: 16} as const;
-const svgProps = {viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round' as const, strokeLinejoin: 'round' as const, ...iconSize};
-
-const ListIcon = (
- <svg {...svgProps}>
- <path d="M8.25 6.75h12M8.25 12h12M8.25 17.25h12M3.75 6.75h.007v.008H3.75V6.75Zm.375 0a.375.375 0 1 1-.75 0 .375.375 0 0 1 .75 0ZM3.75 12h.007v.008H3.75V12Zm.375 0a.375.375 0 1 1-.75 0 .375.375 0 0 1 .75 0Zm-.375 5.25h.007v.008H3.75v-.008Zm.375 0a.375.375 0 1 1-.75 0 .375.375 0 0 1 .75 0Z" />
- </svg>
-);
-
-const GridIcon = (
- <svg {...svgProps}>
- <path d="M3.75 6A2.25 2.25 0 0 1 6 3.75h2.25A2.25 2.25 0 0 1 10.5 6v2.25a2.25 2.25 0 0 1-2.25 2.25H6a2.25 2.25 0 0 1-2.25-2.25V6ZM3.75 15.75A2.25 2.25 0 0 1 6 13.5h2.25a2.25 2.25 0 0 1 2.25 2.25V18a2.25 2.25 0 0 1-2.25 2.25H6A2.25 2.25 0 0 1 3.75 18v-2.25ZM13.5 6a2.25 2.25 0 0 1 2.25-2.25H18A2.25 2.25 0 0 1 20.25 6v2.25A2.25 2.25 0 0 1 18 10.5h-2.25a2.25 2.25 0 0 1-2.25-2.25V6ZM13.5 15.75a2.25 2.25 0 0 1 2.25-2.25H18a2.25 2.25 0 0 1 2.25 2.25V18A2.25 2.25 0 0 1 18 20.25h-2.25a2.25 2.25 0 0 1-2.25-2.25v-2.25Z" />
- </svg>
-);
-
-export default function ToggleButtonGroupSingle() {
- const [view, setView] = useState<string | null>('list');
- return (
- <XDSToggleButtonGroup value={view} onChange={setView} label="View mode">
- <XDSToggleButton
- value="list"
- label="List view"
- icon={ListIcon}
- isIconOnly
- />
- <XDSToggleButton
- value="grid"
- label="Grid view"
- icon={GridIcon}
- isIconOnly
- />
- </XDSToggleButtonGroup>
- );
-}
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonIconSwap.doc.mjs b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonIconSwap.doc.mjs
index 7bdd158431..eaaee90d78 100644
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonIconSwap.doc.mjs
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonIconSwap.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'ToggleButton — Icon Swap',
- description:
- 'Icon-only toggle buttons that swap between outline and solid icons when pressed.',
+ description: 'Icon-only toggle buttons that swap between outline and solid icons when pressed. Use for actions like favorite, bookmark, or mute where the icon itself communicates the state.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ToggleButton'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ToggleButton', 'Layout', 'Text', 'Icon'],
};
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonIconSwap.tsx b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonIconSwap.tsx
index dc1316b797..0124c39f2f 100644
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonIconSwap.tsx
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonIconSwap.tsx
@@ -2,56 +2,48 @@
import {useState} from 'react';
import {XDSToggleButton} from '@xds/core/ToggleButton';
-
-const iconSize = {width: 16, height: 16} as const;
-const svgProps = {viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round' as const, strokeLinejoin: 'round' as const, ...iconSize};
-
-const StarOutline = (
- <svg {...svgProps}>
- <path d="M11.48 3.499a.562.562 0 0 1 1.04 0l2.125 5.111a.563.563 0 0 0 .475.345l5.518.442c.499.04.701.663.321.988l-4.204 3.602a.563.563 0 0 0-.182.557l1.285 5.385a.562.562 0 0 1-.84.61l-4.725-2.885a.562.562 0 0 0-.586 0L6.982 20.54a.562.562 0 0 1-.84-.61l1.285-5.386a.562.562 0 0 0-.182-.557l-4.204-3.602a.562.562 0 0 1 .321-.988l5.518-.442a.563.563 0 0 0 .475-.345L11.48 3.5z" />
- </svg>
-);
-
-const StarSolid = (
- <svg {...iconSize} viewBox="0 0 24 24" fill="currentColor">
- <path fillRule="evenodd" d="M10.788 3.21c.448-1.077 1.976-1.077 2.424 0l2.082 5.006 5.404.434c1.164.093 1.636 1.545.749 2.305l-4.117 3.527 1.257 5.273c.271 1.136-.964 2.033-1.96 1.425L12 18.354 7.373 21.18c-.996.608-2.231-.29-1.96-1.425l1.257-5.273-4.117-3.527c-.887-.76-.415-2.212.749-2.305l5.404-.434 2.082-5.005Z" clipRule="evenodd" />
- </svg>
-);
-
-const BookmarkOutline = (
- <svg {...svgProps}>
- <path d="M17.593 3.322c1.1.128 1.907 1.077 1.907 2.185V21L12 17.25 4.5 21V5.507c0-1.108.806-2.057 1.907-2.185a48.507 48.507 0 0 1 11.186 0Z" />
- </svg>
-);
-
-const BookmarkSolid = (
- <svg {...iconSize} viewBox="0 0 24 24" fill="currentColor">
- <path fillRule="evenodd" d="M6.32 2.577a49.255 49.255 0 0 1 11.36 0c1.497.174 2.57 1.46 2.57 2.93V21a.75.75 0 0 1-1.085.67L12 18.089l-7.165 3.583A.75.75 0 0 1 3.75 21V5.507c0-1.47 1.073-2.756 2.57-2.93Z" clipRule="evenodd" />
- </svg>
-);
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {XDSIcon} from '@xds/core/Icon';
+import {StarIcon as StarOutline, BookmarkIcon as BookmarkOutline, BellIcon, BellSlashIcon} from '@heroicons/react/24/outline';
+import {StarIcon as StarSolid, BookmarkIcon as BookmarkSolid} from '@heroicons/react/24/solid';
export default function ToggleButtonIconSwap() {
const [isFavorited, setIsFavorited] = useState(false);
const [isBookmarked, setIsBookmarked] = useState(true);
+ const [isMuted, setIsMuted] = useState(false);
return (
- <div style={{display: 'flex', gap: 8}}>
- <XDSToggleButton
- label="Favorite"
- icon={StarOutline}
- pressedIcon={StarSolid}
- isPressed={isFavorited}
- onPressedChange={setIsFavorited}
- isIconOnly
- />
- <XDSToggleButton
- label="Bookmark"
- icon={BookmarkOutline}
- pressedIcon={BookmarkSolid}
- isPressed={isBookmarked}
- onPressedChange={setIsBookmarked}
- isIconOnly
- />
- </div>
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Outline → solid icon swap on press
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSToggleButton
+ label="Favorite"
+ icon={<XDSIcon icon={StarOutline} />}
+ pressedIcon={<XDSIcon icon={StarSolid} />}
+ isPressed={isFavorited}
+ onPressedChange={setIsFavorited}
+ isIconOnly
+ />
+ <XDSToggleButton
+ label="Bookmark"
+ icon={<XDSIcon icon={BookmarkOutline} />}
+ pressedIcon={<XDSIcon icon={BookmarkSolid} />}
+ isPressed={isBookmarked}
+ onPressedChange={setIsBookmarked}
+ isIconOnly
+ />
+ <XDSToggleButton
+ label={isMuted ? 'Unmute notifications' : 'Mute notifications'}
+ icon={<XDSIcon icon={BellIcon} />}
+ pressedIcon={<XDSIcon icon={BellSlashIcon} />}
+ isPressed={isMuted}
+ onPressedChange={setIsMuted}
+ isIconOnly
+ />
+ </XDSStack>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonMultiSelect.doc.mjs b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonMultiSelect.doc.mjs
new file mode 100644
index 0000000000..902f86b0f6
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonMultiSelect.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ToggleButton — Multi Select',
+ description: 'Multi-select toggle group forming a text formatting toolbar. Multiple options can be active simultaneously — bold, italic, and underline.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ToggleButton', 'ToggleButtonGroup', 'Layout', 'Text', 'Icon'],
+};
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonMultiSelect.tsx b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonMultiSelect.tsx
new file mode 100644
index 0000000000..22a802fa8b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonMultiSelect.tsx
@@ -0,0 +1,50 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSToggleButton, XDSToggleButtonGroup} from '@xds/core/ToggleButton';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {XDSIcon} from '@xds/core/Icon';
+import {BoldIcon, ItalicIcon, UnderlineIcon, StrikethroughIcon} from '@heroicons/react/24/outline';
+
+export default function ToggleButtonMultiSelect() {
+ const [formats, setFormats] = useState<string[]>(['bold']);
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Text formatting — multiple active at once
+ </XDSText>
+ <XDSToggleButtonGroup
+ type="multiple"
+ value={formats}
+ onChange={setFormats}
+ label="Text formatting">
+ <XDSToggleButton
+ value="bold"
+ label="Bold"
+ icon={<XDSIcon icon={BoldIcon} />}
+ isIconOnly
+ />
+ <XDSToggleButton
+ value="italic"
+ label="Italic"
+ icon={<XDSIcon icon={ItalicIcon} />}
+ isIconOnly
+ />
+ <XDSToggleButton
+ value="underline"
+ label="Underline"
+ icon={<XDSIcon icon={UnderlineIcon} />}
+ isIconOnly
+ />
+ <XDSToggleButton
+ value="strikethrough"
+ label="Strikethrough"
+ icon={<XDSIcon icon={StrikethroughIcon} />}
+ isIconOnly
+ />
+ </XDSToggleButtonGroup>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonNotificationToggle.doc.mjs b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonNotificationToggle.doc.mjs
deleted file mode 100644
index eba8714d43..0000000000
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonNotificationToggle.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'ToggleButton — Notification Toggle',
- description:
- 'Toggle button that swaps between bell and bell-slash icons to mute/unmute notifications.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ToggleButton'],
-};
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonNotificationToggle.tsx b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonNotificationToggle.tsx
deleted file mode 100644
index 03d38b257c..0000000000
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonNotificationToggle.tsx
+++ /dev/null
@@ -1,33 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSToggleButton} from '@xds/core/ToggleButton';
-
-const iconSize = {width: 16, height: 16} as const;
-const svgProps = {viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round' as const, strokeLinejoin: 'round' as const, ...iconSize};
-
-const BellIcon = (
- <svg {...svgProps}>
- <path d="M14.857 17.082a23.848 23.848 0 0 0 5.454-1.31A8.967 8.967 0 0 1 18 9.75V9A6 6 0 0 0 6 9v.75a8.967 8.967 0 0 1-2.312 6.022c1.733.64 3.56 1.085 5.455 1.31m5.714 0a24.255 24.255 0 0 1-5.714 0m5.714 0a3 3 0 1 1-5.714 0" />
- </svg>
-);
-
-const BellSlashIcon = (
- <svg {...svgProps}>
- <path d="M9.143 17.082a24.248 24.248 0 0 0 5.714 0m-5.714 0a3 3 0 1 0 5.714 0M9.143 17.082a23.848 23.848 0 0 1-5.454-1.31A8.967 8.967 0 0 0 6 9.75V9a6 6 0 0 1 .597-2.601M3 3l18 18M17.94 12.85A8.956 8.956 0 0 0 18 9.75V9a6 6 0 0 0-9.22-5.06" />
- </svg>
-);
-
-export default function ToggleButtonNotificationToggle() {
- const [isMuted, setIsMuted] = useState(false);
- return (
- <XDSToggleButton
- label={isMuted ? 'Unmute notifications' : 'Mute notifications'}
- icon={BellIcon}
- pressedIcon={BellSlashIcon}
- isPressed={isMuted}
- onPressedChange={setIsMuted}
- isIconOnly
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonShowcase.doc.mjs b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonShowcase.doc.mjs
index 589814a486..d59533bb1e 100644
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonShowcase.doc.mjs
@@ -3,6 +3,6 @@ export const doc = {
type: 'block',
name: 'ToggleButton',
isReady: true,
- aspectRatio: 1,
+ aspectRatio: 16 / 9,
isShowcase: true,
};
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonShowcase.tsx b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonShowcase.tsx
index e52d6b1889..c747a11efd 100644
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonShowcase.tsx
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonShowcase.tsx
@@ -1,20 +1,43 @@
-import {XDSToggleButton} from '@xds/core/ToggleButton';
+'use client';
-const BoldIcon = (
- <svg width={16} height={16} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round">
- <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
- <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
- </svg>
-);
+import {useState} from 'react';
+import {XDSToggleButton} from '@xds/core/ToggleButton';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSIcon} from '@xds/core/Icon';
+import {StarIcon as StarOutline, BookmarkIcon as BookmarkOutline, BellIcon, BellSlashIcon} from '@heroicons/react/24/outline';
+import {StarIcon as StarSolid, BookmarkIcon as BookmarkSolid} from '@heroicons/react/24/solid';
export default function ToggleButtonShowcase() {
+ const [isFavorited, setIsFavorited] = useState(false);
+ const [isBookmarked, setIsBookmarked] = useState(true);
+ const [isMuted, setIsMuted] = useState(false);
+
return (
- <XDSToggleButton
- label="Bold"
- icon={BoldIcon}
- isPressed={false}
- onPressedChange={() => {}}
- isIconOnly
- />
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSToggleButton
+ label="Favorite"
+ icon={<XDSIcon icon={StarOutline} />}
+ pressedIcon={<XDSIcon icon={StarSolid} />}
+ isPressed={isFavorited}
+ onPressedChange={setIsFavorited}
+ isIconOnly
+ />
+ <XDSToggleButton
+ label="Bookmark"
+ icon={<XDSIcon icon={BookmarkOutline} />}
+ pressedIcon={<XDSIcon icon={BookmarkSolid} />}
+ isPressed={isBookmarked}
+ onPressedChange={setIsBookmarked}
+ isIconOnly
+ />
+ <XDSToggleButton
+ label="Notifications"
+ icon={<XDSIcon icon={BellIcon} />}
+ pressedIcon={<XDSIcon icon={BellSlashIcon} />}
+ isPressed={isMuted}
+ onPressedChange={setIsMuted}>
+ Notifications
+ </XDSToggleButton>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonSingleSelect.doc.mjs b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonSingleSelect.doc.mjs
new file mode 100644
index 0000000000..115498e468
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonSingleSelect.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ToggleButton — Single Select',
+ description: 'Single-select toggle group acting as a view mode switcher. Only one option can be active at a time — clicking the active button deselects it.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ToggleButton', 'ToggleButtonGroup', 'Layout', 'Text', 'Icon'],
+};
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonSingleSelect.tsx b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonSingleSelect.tsx
new file mode 100644
index 0000000000..1edad146da
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonSingleSelect.tsx
@@ -0,0 +1,40 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSToggleButton, XDSToggleButtonGroup} from '@xds/core/ToggleButton';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {XDSIcon} from '@xds/core/Icon';
+import {ListBulletIcon, Squares2X2Icon, TableCellsIcon} from '@heroicons/react/24/outline';
+
+export default function ToggleButtonSingleSelect() {
+ const [view, setView] = useState<string | null>('list');
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ View mode switcher — one active at a time
+ </XDSText>
+ <XDSToggleButtonGroup value={view} onChange={setView} label="View mode">
+ <XDSToggleButton
+ value="list"
+ label="List view"
+ icon={<XDSIcon icon={ListBulletIcon} />}
+ isIconOnly
+ />
+ <XDSToggleButton
+ value="grid"
+ label="Grid view"
+ icon={<XDSIcon icon={Squares2X2Icon} />}
+ isIconOnly
+ />
+ <XDSToggleButton
+ value="table"
+ label="Table view"
+ icon={<XDSIcon icon={TableCellsIcon} />}
+ isIconOnly
+ />
+ </XDSToggleButtonGroup>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonStates.doc.mjs b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonStates.doc.mjs
new file mode 100644
index 0000000000..b6c925449d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonStates.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ToggleButton — States',
+ description: 'Default, pressed, disabled, and loading states of a standalone toggle button. Shows how visual treatment changes across states.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ToggleButton', 'Layout', 'Text', 'Icon'],
+};
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonStates.tsx b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonStates.tsx
new file mode 100644
index 0000000000..edae079e7e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonStates.tsx
@@ -0,0 +1,103 @@
+'use client';
+
+import {XDSToggleButton} from '@xds/core/ToggleButton';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {XDSIcon} from '@xds/core/Icon';
+import {StarIcon as StarOutline} from '@heroicons/react/24/outline';
+import {StarIcon as StarSolid} from '@heroicons/react/24/solid';
+
+export default function ToggleButtonStates() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Default
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSToggleButton
+ label="Favorite"
+ icon={<XDSIcon icon={StarOutline} />}
+ pressedIcon={<XDSIcon icon={StarSolid} />}
+ isPressed={false}
+ onPressedChange={() => {}}
+ />
+ <XDSToggleButton
+ label="Favorite"
+ icon={<XDSIcon icon={StarOutline} />}
+ pressedIcon={<XDSIcon icon={StarSolid} />}
+ isPressed={false}
+ onPressedChange={() => {}}
+ isIconOnly
+ />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Pressed
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSToggleButton
+ label="Favorite"
+ icon={<XDSIcon icon={StarOutline} />}
+ pressedIcon={<XDSIcon icon={StarSolid} />}
+ isPressed={true}
+ onPressedChange={() => {}}
+ />
+ <XDSToggleButton
+ label="Favorite"
+ icon={<XDSIcon icon={StarOutline} />}
+ pressedIcon={<XDSIcon icon={StarSolid} />}
+ isPressed={true}
+ onPressedChange={() => {}}
+ isIconOnly
+ />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Disabled
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSToggleButton
+ label="Favorite"
+ icon={<XDSIcon icon={StarOutline} />}
+ isPressed={false}
+ onPressedChange={() => {}}
+ isDisabled
+ />
+ <XDSToggleButton
+ label="Favorite"
+ icon={<XDSIcon icon={StarOutline} />}
+ isPressed={false}
+ onPressedChange={() => {}}
+ isIconOnly
+ isDisabled
+ />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Loading
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSToggleButton
+ label="Favorite"
+ icon={<XDSIcon icon={StarOutline} />}
+ isPressed={false}
+ onPressedChange={() => {}}
+ isLoading
+ />
+ <XDSToggleButton
+ label="Favorite"
+ icon={<XDSIcon icon={StarOutline} />}
+ isPressed={false}
+ onPressedChange={() => {}}
+ isIconOnly
+ isLoading
+ />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonWithLabel.doc.mjs b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonWithLabel.doc.mjs
index 0af46504d5..aaa437f319 100644
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonWithLabel.doc.mjs
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonWithLabel.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'ToggleButton — With Label',
- description:
- 'Toggle button with visible label text that shows a font weight shift on press.',
+ description: 'Toggle buttons with visible text labels that show a font weight shift on press. Use when the icon alone is not enough to communicate the action.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ToggleButton'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ToggleButton', 'ToggleButtonGroup', 'Layout', 'Text', 'Icon'],
};
diff --git a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonWithLabel.tsx b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonWithLabel.tsx
index 79de1e84b8..e5b40ddf0a 100644
--- a/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonWithLabel.tsx
+++ b/packages/cli/templates/blocks/components/ToggleButton/ToggleButtonWithLabel.tsx
@@ -1,16 +1,56 @@
'use client';
import {useState} from 'react';
-import {XDSToggleButton} from '@xds/core/ToggleButton';
+import {XDSToggleButton, XDSToggleButtonGroup} from '@xds/core/ToggleButton';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {XDSIcon} from '@xds/core/Icon';
+import {EyeIcon, EyeSlashIcon, FunnelIcon, MapPinIcon} from '@heroicons/react/24/outline';
export default function ToggleButtonWithLabel() {
- const [isActive, setIsActive] = useState(false);
+ const [isVisible, setIsVisible] = useState(true);
+ const [filters, setFilters] = useState<string[]>([]);
+
return (
- <XDSToggleButton
- label="Active"
- isPressed={isActive}
- onPressedChange={setIsActive}>
- Active
- </XDSToggleButton>
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Standalone with label and icon
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSToggleButton
+ label="Visible"
+ icon={<XDSIcon icon={EyeIcon} />}
+ pressedIcon={<XDSIcon icon={EyeSlashIcon} />}
+ isPressed={isVisible}
+ onPressedChange={setIsVisible}>
+ {isVisible ? 'Visible' : 'Hidden'}
+ </XDSToggleButton>
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Labeled group — filter toolbar
+ </XDSText>
+ <XDSToggleButtonGroup
+ type="multiple"
+ value={filters}
+ onChange={setFilters}
+ label="Filters">
+ <XDSToggleButton
+ value="filter"
+ label="Filter"
+ icon={<XDSIcon icon={FunnelIcon} />}>
+ Filter
+ </XDSToggleButton>
+ <XDSToggleButton
+ value="nearby"
+ label="Nearby"
+ icon={<XDSIcon icon={MapPinIcon} />}>
+ Nearby
+ </XDSToggleButton>
+ </XDSToggleButtonGroup>
+ </XDSStack>
+ </XDSStack>
);
}
diff --git a/packages/core/src/ToggleButton/ToggleButton.doc.mjs b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
index 72e6059510..a77cf7300c 100644
--- a/packages/core/src/ToggleButton/ToggleButton.doc.mjs
+++ b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
@@ -47,12 +47,20 @@ export const docs = {
],
usage: {
description:
- 'ToggleButton is a button that switches between pressed and unpressed states to represent a persistent on/off choice. Use it standalone for binary actions like bold or mute, or within a ToggleButtonGroup for single-select or multi-select toolbar options.',
+ 'ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.',
bestPractices: [
- { guidance: true, description: 'Convey the pressed state through a filled icon, bold text, or color change so users can see the current state at a glance.' },
- { guidance: true, description: 'Keep the label the same between pressed and unpressed states — let the visual treatment communicate the change.' },
- { guidance: false, description: 'Use a ToggleButton for actions that navigate to another page or trigger a one-time event — use Button instead.' },
- { guidance: false, description: 'Mix ToggleButtons with regular Buttons in the same group.' },
+ {guidance: true, description: 'Use a filled or colored icon for the pressed state so users can see the current state at a glance — an outline star vs a solid star, for example.'},
+ {guidance: true, description: 'Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change.'},
+ {guidance: true, description: 'Wrap related toggles in a ToggleButtonGroup with an accessible label so screen readers announce them as a connected set.'},
+ {guidance: false, description: "Don't use a ToggleButton for one-time actions like \"Submit\" or \"Delete\" — those are regular Buttons, not toggles."},
+ {guidance: false, description: "Don't mix ToggleButtons with regular Buttons inside the same group — use only ToggleButtons in a ToggleButtonGroup."},
+ {guidance: false, description: "Don't use a ToggleButton for on/off settings that persist across sessions — use a Switch instead, which better communicates \"setting\" semantics."},
+ ],
+ anatomy: [
+ {name: 'Icon', required: false, description: 'A leading icon that represents the toggle action, like a star for favorite or bold "B" for formatting.'},
+ {name: 'Pressed icon', required: false, description: 'An alternate icon shown when pressed — typically a filled version of the default icon to reinforce the active state.'},
+ {name: 'Label', required: true, description: 'The visible text or accessible name. For icon-only toggles, used as the aria-label and auto-tooltip.'},
+ {name: 'Spinner', required: false, description: 'Replaces the icon during async operations triggered by onPressedChangeAction.'},
],
},
};
@@ -98,12 +106,20 @@ export const docsZh = {
],
usage: {
description:
- 'ToggleButton is a button that switches between pressed and unpressed states to represent a persistent on/off choice. Use it standalone for binary actions like bold or mute, or within a ToggleButtonGroup for single-select or multi-select toolbar options.',
+ 'ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.',
bestPractices: [
- { guidance: true, description: 'Convey the pressed state through a filled icon, bold text, or color change so users can see the current state at a glance.' },
- { guidance: true, description: 'Keep the label the same between pressed and unpressed states — let the visual treatment communicate the change.' },
- { guidance: false, description: 'Use a ToggleButton for actions that navigate to another page or trigger a one-time event — use Button instead.' },
- { guidance: false, description: 'Mix ToggleButtons with regular Buttons in the same group.' },
+ {guidance: true, description: 'Use a filled or colored icon for the pressed state so users can see the current state at a glance — an outline star vs a solid star, for example.'},
+ {guidance: true, description: 'Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change.'},
+ {guidance: true, description: 'Wrap related toggles in a ToggleButtonGroup with an accessible label so screen readers announce them as a connected set.'},
+ {guidance: false, description: "Don't use a ToggleButton for one-time actions like \"Submit\" or \"Delete\" — those are regular Buttons, not toggles."},
+ {guidance: false, description: "Don't mix ToggleButtons with regular Buttons inside the same group — use only ToggleButtons in a ToggleButtonGroup."},
+ {guidance: false, description: "Don't use a ToggleButton for on/off settings that persist across sessions — use a Switch instead, which better communicates \"setting\" semantics."},
+ ],
+ anatomy: [
+ {name: 'Icon', required: false, description: 'A leading icon that represents the toggle action, like a star for favorite or bold "B" for formatting.'},
+ {name: 'Pressed icon', required: false, description: 'An alternate icon shown when pressed — typically a filled version of the default icon to reinforce the active state.'},
+ {name: 'Label', required: true, description: 'The visible text or accessible name. For icon-only toggles, used as the aria-label and auto-tooltip.'},
+ {name: 'Spinner', required: false, description: 'Replaces the icon during async operations triggered by onPressedChangeAction.'},
],
},
};
@@ -113,12 +129,14 @@ export const docsDense = {
description: 'toggle btn w/ pressed/unpressed states, icon swap, group integration for single/multi-select',
usage: {
description:
- 'ToggleButton is a button that switches between pressed and unpressed states to represent a persistent on/off choice. Use it standalone for binary actions like bold or mute, or within a ToggleButtonGroup for single-select or multi-select toolbar options.',
+ 'ToggleButton switches between selected/unselected for persistent on/off choices. Standalone for binary actions or in ToggleButtonGroup for single/multi-select toolbar controls.',
bestPractices: [
- { guidance: true, description: 'Convey the pressed state through a filled icon, bold text, or color change so users can see the current state at a glance.' },
- { guidance: true, description: 'Keep the label the same between pressed and unpressed states — let the visual treatment communicate the change.' },
- { guidance: false, description: 'Use a ToggleButton for actions that navigate to another page or trigger a one-time event — use Button instead.' },
- { guidance: false, description: 'Mix ToggleButtons with regular Buttons in the same group.' },
+ {guidance: true, description: 'Filled/colored icon for pressed state so users see current state at a glance.'},
+ {guidance: true, description: 'Keep label identical between states. Let visual treatment communicate the change.'},
+ {guidance: true, description: 'Wrap related toggles in ToggleButtonGroup with accessible label.'},
+ {guidance: false, description: "Don't use ToggleButton for one-time actions — use regular Button for submit/delete."},
+ {guidance: false, description: "Don't mix ToggleButtons with regular Buttons in the same group."},
+ {guidance: false, description: "Don't use ToggleButton for persistent settings — use Switch instead."},
],
},
components: [