+
{ children }
);
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
index 2acd609992d6ad..bd85b61ae6ece7 100644
--- a/packages/components/src/index.ts
+++ b/packages/components/src/index.ts
@@ -175,11 +175,7 @@ export { default as TextareaControl } from './textarea-control';
export { default as TextHighlight } from './text-highlight';
export { default as Tip } from './tip';
export { default as ToggleControl } from './toggle-control';
-export {
- ToggleGroupControl as __experimentalToggleGroupControl,
- ToggleGroupControlOption as __experimentalToggleGroupControlOption,
- ToggleGroupControlOptionIcon as __experimentalToggleGroupControlOptionIcon,
-} from './toggle-group-control';
+export { ToggleGroupControl as __experimentalToggleGroupControl } from './toggle-group-control';
export {
Toolbar,
ToolbarButton,
diff --git a/packages/components/src/toggle-group-control/README.md b/packages/components/src/toggle-group-control/README.md
new file mode 100644
index 00000000000000..e3fea28bd36191
--- /dev/null
+++ b/packages/components/src/toggle-group-control/README.md
@@ -0,0 +1,158 @@
+# ToggleGroupControl
+
+
+
+See the WordPress Storybook for more detailed, interactive documentation.
+
+ToggleGroupControl is a form component that lets users choose options
+from a group of toggle buttons. It provides a single-selection interface
+with a consistent visual design.
+
+## Props
+
+### `__nextHasNoMarginBottom`
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+### `__next40pxDefaultSize`
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+Start opting into the larger default height that will become the default size in a future version.
+
+### `children`
+
+ - Type: `ReactNode`
+ - Required: Yes
+
+The options to render in the `ToggleGroupControl`, using either the `ToggleGroupControlOption` or
+`ToggleGroupControlOptionIcon` components.
+
+### `help`
+
+ - Type: `ReactNode`
+ - Required: No
+
+Additional description for the control.
+
+Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an `aria-describedby` attribute.
+
+### `hideLabelFromVision`
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+If true, the label will only be visible to screen readers.
+
+### `isAdaptiveWidth`
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+Determines if segments should be rendered with equal widths.
+
+### `isBlock`
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+Renders `ToggleGroupControl` as a (CSS) block element, spanning the entire width of
+the available space. This is the recommended style when the options are text-based and not icons.
+
+### `isDeselectable`
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+Whether an option can be deselected by clicking it again.
+
+### `label`
+
+ - Type: `string`
+ - Required: Yes
+
+Label for the control.
+
+### `onChange`
+
+ - Type: `(value: string | number) => void`
+ - Required: No
+
+Callback when a segment is selected.
+
+### `size`
+
+ - Type: `"default" | "__unstable-large"`
+ - Required: No
+ - Default: `'default'`
+
+The size variant of the control.
+
+### `value`
+
+ - Type: `string | number`
+ - Required: No
+
+The selected value.
+
+## Subcomponents
+
+### ToggleGroupControl.Option
+
+#### Props
+
+##### `label`
+
+ - Type: `string`
+ - Required: Yes
+
+Label for the option. If needed, the `aria-label` prop can be used in addition
+to specify a different label for assistive technologies.
+
+##### `showTooltip`
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+Whether to display a Tooltip for the control option. If set to `true`, the tooltip will
+show the aria-label or the label prop text.
+
+##### `value`
+
+ - Type: `string | number`
+ - Required: Yes
+
+### ToggleGroupControl.OptionIcon
+
+#### Props
+
+##### `icon`
+
+ - Type: `Element`
+ - Required: Yes
+
+Icon displayed as the content of the option. Usually one of the icons from
+the `@wordpress/icons` package, or a custom React `` icon.
+
+##### `label`
+
+ - Type: `string`
+ - Required: Yes
+
+The text to accessibly label the icon option. Will also be shown in a tooltip.
+
+##### `value`
+
+ - Type: `string | number`
+ - Required: Yes
diff --git a/packages/components/src/toggle-group-control/docs-manifest.json b/packages/components/src/toggle-group-control/docs-manifest.json
new file mode 100644
index 00000000000000..c9ddf10ccca309
--- /dev/null
+++ b/packages/components/src/toggle-group-control/docs-manifest.json
@@ -0,0 +1,17 @@
+{
+ "$schema": "../../schemas/docs-manifest.json",
+ "displayName": "ToggleGroupControl",
+ "filePath": "./index.ts",
+ "subcomponents": [
+ {
+ "displayName": "ToggleGroupControlOption",
+ "preferredDisplayName": "ToggleGroupControl.Option",
+ "filePath": "./toggle-group-control-option/index.ts"
+ },
+ {
+ "displayName": "ToggleGroupControlOptionIcon",
+ "preferredDisplayName": "ToggleGroupControl.OptionIcon",
+ "filePath": "./toggle-group-control-option-icon/index.ts"
+ }
+ ]
+}
diff --git a/packages/components/src/toggle-group-control/index.ts b/packages/components/src/toggle-group-control/index.ts
index e5e40497d9220e..85cd8696d157f4 100644
--- a/packages/components/src/toggle-group-control/index.ts
+++ b/packages/components/src/toggle-group-control/index.ts
@@ -1,3 +1,30 @@
-export { ToggleGroupControl } from './toggle-group-control';
-export { ToggleGroupControlOption } from './toggle-group-control-option';
-export { ToggleGroupControlOptionIcon } from './toggle-group-control-option-icon';
+/**
+ * Internal dependencies
+ */
+import { ToggleGroupControl as BaseToggleGroupControl } from './toggle-group-control';
+import { ToggleGroupControlOption } from './toggle-group-control-option';
+import { ToggleGroupControlOptionIcon } from './toggle-group-control-option-icon';
+
+/**
+ * ToggleGroupControl is a form component that lets users choose options
+ * from a group of toggle buttons. It provides a single-selection interface
+ * with a consistent visual design.
+ */
+export const ToggleGroupControl = Object.assign( BaseToggleGroupControl, {
+ /**
+ * Renders a standard toggle option button within a ToggleGroupControl.
+ * Used for text-based toggle options.
+ */
+ Option: Object.assign( ToggleGroupControlOption, {
+ displayName: 'ToggleGroupControl.Option',
+ } ),
+ /**
+ * Renders an icon toggle option button within a ToggleGroupControl.
+ * Used for icon-based toggle options.
+ */
+ OptionIcon: Object.assign( ToggleGroupControlOptionIcon, {
+ displayName: 'ToggleGroupControl.OptionIcon',
+ } ),
+} );
+
+export default ToggleGroupControl;
diff --git a/packages/components/src/toggle-group-control/stories/best-practices.mdx b/packages/components/src/toggle-group-control/stories/best-practices.mdx
new file mode 100644
index 00000000000000..18b715a25ccbc3
--- /dev/null
+++ b/packages/components/src/toggle-group-control/stories/best-practices.mdx
@@ -0,0 +1,33 @@
+# `ToggleGroupControl`
+
+
+ This feature is still experimental. “Experimental” means this is an early
+ implementation subject to drastic and breaking changes.
+
+
+`ToggleGroupControl` is a form component that lets users choose options represented in horizontal segments. To render options for this control use [`ToggleGroupControlOption`](/packages/components/src/toggle-group-control/toggle-group-control-option/README.md) component.
+
+This component is intended for selecting a single persistent value from a set of options, similar to a how a radio button group would work. If you simply want a toggle to switch between views, use a [`TabPanel`](/packages/components/src/tab-panel/README.md) instead.
+
+Only use this control when you know for sure the labels of items inside won't wrap. For items with longer labels, you can consider a [`SelectControl`](/packages/components/src/select-control/README.md) or a [`CustomSelectControl`](/packages/components/src/custom-select-control/README.md) component instead.
+
+## Usage
+
+```js
+import { __experimentalToggleGroupControl as ToggleGroupControl } from '@wordpress/components';
+
+function Example() {
+ return (
+
+
+ );
+}
+```
diff --git a/packages/components/src/toggle-group-control/stories/index.story.tsx b/packages/components/src/toggle-group-control/stories/index.story.tsx
index 0f3c0a299617af..457a2453ff0646 100644
--- a/packages/components/src/toggle-group-control/stories/index.story.tsx
+++ b/packages/components/src/toggle-group-control/stories/index.story.tsx
@@ -12,11 +12,7 @@ import { formatLowercase, formatUppercase } from '@wordpress/icons';
/**
* Internal dependencies
*/
-import {
- ToggleGroupControl,
- ToggleGroupControlOption,
- ToggleGroupControlOptionIcon,
-} from '../index';
+import { ToggleGroupControl } from '../index';
import type {
ToggleGroupControlOptionProps,
ToggleGroupControlOptionIconProps,
@@ -25,8 +21,12 @@ import type {
const meta: Meta< typeof ToggleGroupControl > = {
component: ToggleGroupControl,
- // @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
- subcomponents: { ToggleGroupControlOption, ToggleGroupControlOptionIcon },
+ subcomponents: {
+ // @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+ Option: ToggleGroupControl.Option,
+ // @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+ OptionIcon: ToggleGroupControl.OptionIcon,
+ },
title: 'Components (Experimental)/Selection & Input/ToggleGroupControl',
id: 'components-experimental-togglegroupcontrol',
argTypes: {
@@ -66,14 +66,14 @@ const mapPropsToOptionComponent = ( {
value,
...props
}: ToggleGroupControlOptionProps ) => (
-
-
-
- *
-
- *
-`ToggleGroupControlOption` is a form component and is meant to be used as a child of [`ToggleGroupControl`](/packages/components/src/toggle-group-control/toggle-group-control/README.md).
+`ToggleGroupControl.Option` is a form component and is meant to be used as a child of [`ToggleGroupControl`](/packages/components/src/toggle-group-control/toggle-group-control/README.md).
## Usage
```js
-import {
- __experimentalToggleGroupControl as ToggleGroupControl,
- __experimentalToggleGroupControlOption as ToggleGroupControlOption,
-} from '@wordpress/components';
+import { __experimentalToggleGroupControl as ToggleGroupControl } from '@wordpress/components';
function Example() {
return (
@@ -23,12 +20,12 @@ function Example() {
__nextHasNoMarginBottom
__next40pxDefaultSize
>
-
);
}
diff --git a/packages/components/src/toggle-group-control/toggle-group-control-option/component.tsx b/packages/components/src/toggle-group-control/toggle-group-control-option/component.tsx
index 8632d92fc00578..74238e15657f89 100644
--- a/packages/components/src/toggle-group-control/toggle-group-control-option/component.tsx
+++ b/packages/components/src/toggle-group-control/toggle-group-control-option/component.tsx
@@ -37,13 +37,12 @@ function UnforwardedToggleGroupControlOption(
}
/**
- * `ToggleGroupControlOption` is a form component and is meant to be used as a
+ * `ToggleGroupControl.Option` is a form component and is meant to be used as a
* child of `ToggleGroupControl`.
*
* ```jsx
* import {
* __experimentalToggleGroupControl as ToggleGroupControl,
- * __experimentalToggleGroupControlOption as ToggleGroupControlOption,
* } from '@wordpress/components';
*
* function Example() {
@@ -55,8 +54,8 @@ function UnforwardedToggleGroupControlOption(
* __nextHasNoMarginBottom
* __next40pxDefaultSize
* >
- *
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-
-
-`ToggleGroupControl` is a form component that lets users choose options represented in horizontal segments. To render options for this control use [`ToggleGroupControlOption`](/packages/components/src/toggle-group-control/toggle-group-control-option/README.md) component.
-
-This component is intended for selecting a single persistent value from a set of options, similar to a how a radio button group would work. If you simply want a toggle to switch between views, use a [`TabPanel`](/packages/components/src/tab-panel/README.md) instead.
-
-Only use this control when you know for sure the labels of items inside won't wrap. For items with longer labels, you can consider a [`SelectControl`](/packages/components/src/select-control/README.md) or a [`CustomSelectControl`](/packages/components/src/custom-select-control/README.md) component instead.
-
-## Usage
-
-```js
-import {
- __experimentalToggleGroupControl as ToggleGroupControl,
- __experimentalToggleGroupControlOption as ToggleGroupControlOption,
-} from '@wordpress/components';
-
-function Example() {
- return (
-
-
- );
-}
-```
-
-## Props
-
-### `help`: `ReactNode`
-
-If this property is added, a help text will be generated using help property as the content.
-
-- Required: No
-
-### `hideLabelFromVision`: `boolean`
-
-If true, the label will only be visible to screen readers.
-
-- Required: No
-- Default: `false`
-
-### `isAdaptiveWidth`: `boolean`
-
-Determines if segments should be rendered with equal widths.
-
-- Required: No
-- Default: `false`
-
-### `isDeselectable`: `boolean`
-
-Whether an option can be deselected by clicking it again.
-
-- Required: No
-- Default: `false`
-
-### `isBlock`: `boolean`
-
-Renders `ToggleGroupControl` as a (CSS) block element, spanning the entire width of the available space. This is the recommended style when the options are text-based and not icons.
-
-- Required: No
-- Default: `false`
-
-### `label`: `string`
-
-Label for the form element.
-
-- Required: Yes
-
-### `onChange`: `( value?: string | number ) => void`
-
-Callback when a segment is selected.
-
-- Required: No
-- Default: `() => {}`
-
-### `value`: `string | number`
-
-The value of the `ToggleGroupControl`.
-
-- Required: No
-
-### `__next40pxDefaultSize`: `boolean`
-
-Start opting into the larger default height that will become the default size in a future version.
-
-- Required: No
-- Default: `false`
-
-### `__nextHasNoMarginBottom`: `boolean`
-
-Start opting into the new margin-free styles that will become the default in a future version.
-
-- Required: No
-- Default: `false`
diff --git a/packages/components/src/toggle-group-control/toggle-group-control/component.tsx b/packages/components/src/toggle-group-control/toggle-group-control/component.tsx
index 9f3427e95a6017..ae90e8cd5224a3 100644
--- a/packages/components/src/toggle-group-control/toggle-group-control/component.tsx
+++ b/packages/components/src/toggle-group-control/toggle-group-control/component.tsx
@@ -121,7 +121,7 @@ function UnconnectedToggleGroupControl(
/**
* `ToggleGroupControl` is a form component that lets users choose options
* represented in horizontal segments. To render options for this control use
- * `ToggleGroupControlOption` component.
+ * `ToggleGroupControl.Option` component.
*
* This component is intended for selecting a single persistent value from a set of options,
* similar to a how a radio button group would work. If you simply want a toggle to switch between views,
@@ -134,7 +134,6 @@ function UnconnectedToggleGroupControl(
* ```jsx
* import {
* __experimentalToggleGroupControl as ToggleGroupControl,
- * __experimentalToggleGroupControlOption as ToggleGroupControlOption,
* } from '@wordpress/components';
*
* function Example() {
@@ -146,8 +145,8 @@ function UnconnectedToggleGroupControl(
* __nextHasNoMarginBottom
* __next40pxDefaultSize
* >
- *
{ PAGE_SIZE_VALUES.map( ( value ) => {
return (
-
-
-
-