mirka · Feb 5, 2026 · Jan 20, 2026 · Jan 20, 2026 · Jan 20, 2026 · Jan 20, 2026
@@ -0,0 +1,17 @@
+## Status
+
+This package contains UI components that are intended to be used anywhere in a general way (global), or specifically in the block editor.
+
+We are currently in the process of rewriting the global components to be in the new `@wordpress/ui` package. However, this is a work in progress and `@wordpress/components` should continue to be used until further notice.
+
+Due to the nature of the transition, some components may be deprecated or removed in the future. Check the component status documentation in each Storybook file for up-to-date usage guidance on each component. The component status given in the Storybook file should be considered the most accurate signal, above the `experimental` tag or component prefix.
+
+## Forms
+
+Is the form going to edit items of a dataset, rather than simply submitting data somewhere? If so, consider using `DataForm` from the `@wordpress/dataviews` package.
+
+For adding validation, consider using the [Validated Form Components](./src/validated-form-controls).
+
+## Storybook
+
+Don't forget to check a components's Storybook documentation for additional usage guidance. The Storybook links ([public base URL](https://wordpress.github.io/gutenberg/)) are also useful to present to a human when they are asking for help with a component.
@@ -33,6 +33,10 @@ const meta: Meta< typeof AlignmentMatrixControl > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'editor',
+		},
 	},
 };
 export default meta;

@@ -29,6 +29,10 @@ const meta: Meta< typeof AnglePickerControl > = {
 			expanded: true,
 		},
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'editor',
+		},
 	},
 };
 

@@ -16,6 +16,11 @@ const meta: Meta< typeof Animate > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'not-recommended',
+			whereUsed: 'global',
+			notes: 'Planned for deprecation.',
+		},
 	},
 };
 export default meta;

@@ -13,6 +13,13 @@ const meta: Meta< typeof Badge > = {
 	title: 'Components/Containers/Badge',
 	id: 'components-badge',
 	tags: [ 'status-private' ],
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Will be superseded by `Badge` in `@wordpress/ui`, but continue using for now.',
+		},
+	},
 };
 
 export default meta;

@@ -96,7 +96,7 @@ const UnforwardedVisualLabel = (
 export const VisualLabel = forwardRef( UnforwardedVisualLabel );
 
 /**
- * `BaseControl` is a component used to generate labels and help text for components handling user inputs.
+ * `BaseControl` is a low-level component used to generate labels and help text for components handling user inputs.
  *
  * ```jsx
  * import { BaseControl, useBaseControlProps } from '@wordpress/components';

@@ -24,6 +24,10 @@ const meta: Meta< typeof BaseControl > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 export default meta;

@@ -25,6 +25,10 @@ const meta: Meta< typeof BorderBoxControl > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'editor',
+		},
 	},
 };
 export default meta;

@@ -28,6 +28,10 @@ const meta: Meta< typeof BorderControl > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'editor',
+		},
 	},
 };
 export default meta;

@@ -26,6 +26,11 @@ const meta: Meta< typeof BoxControl > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'editor',
+			notes: 'This component is a fallback for themes that do not supply spacing presets. Most of the time `SpacingSizesControl` from `@wordpress/block-editor` is used instead.',
+		},
 	},
 };
 export default meta;

@@ -52,6 +52,11 @@ const meta: Meta< typeof Button > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+			notes: 'Will be superseded by `Button` in `@wordpress/ui`, but continue using for now.',
+		},
 	},
 };
 export default meta;

@@ -36,6 +36,11 @@ const meta: Meta< typeof Card > = {
 			expanded: true,
 		},
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Design is in flux, and may differ from the version used in `@wordpress/dataviews`.',
+		},
 	},
 };
 

@@ -34,6 +34,10 @@ const meta: Meta< typeof CheckboxControl > = {
 			exclude: [ 'heading' ],
 		},
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 export default meta;

@@ -38,6 +38,11 @@ const meta: Meta< typeof CircularOptionPicker > = {
 			canvas: { sourceState: 'shown' },
 			source: { excludeDecorators: true },
 		},
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Mostly intended for internal use.',
+		},
 	},
 	decorators: [
 		// Share current color state between main component, `actions` and `options`

@@ -22,6 +22,10 @@ const meta: Meta< typeof ColorIndicator > = {
 			expanded: true,
 		},
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 export default meta;

@@ -25,6 +25,10 @@ const meta: Meta< typeof ColorPalette > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 export default meta;

@@ -25,6 +25,10 @@ const meta: Meta< typeof ColorPicker > = {
 			expanded: true,
 		},
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 export default meta;

@@ -48,6 +48,11 @@ const meta: Meta< typeof ComboboxControl > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+			notes: 'Will be superseded by `SearchableSelect` in `@wordpress/ui`, but continue using for now.',
+		},
 	},
 };
 export default meta;

@@ -47,6 +47,10 @@ const meta: Meta< typeof Composite > = {
 		docs: {
 			canvas: { sourceState: 'shown' },
 		},
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 	decorators: [
 		( Story ) => {

@@ -33,6 +33,10 @@ const meta: Meta< typeof ConfirmDialog > = {
 		controls: {
 			expanded: true,
 		},
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 		docs: { canvas: { sourceState: 'shown' } },
 	},
 };

@@ -23,6 +23,11 @@ const meta: Meta< typeof CustomGradientPicker > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'not-recommended',
+			whereUsed: 'global',
+			notes: 'Mostly an internal component. Use `GradientPicker` instead.',
+		},
 	},
 };
 export default meta;

@@ -31,6 +31,11 @@ const meta: Meta< typeof CustomSelectControlV2 > = {
 		docs: {
 			source: { excludeDecorators: true },
 		},
+		componentStatus: {
+			status: 'not-recommended',
+			whereUsed: 'global',
+			notes: 'Will be superseded by `SelectControl` in `@wordpress/ui`. Continue using `CustomSelectControl` (v1) for now.',
+		},
 	},
 	decorators: [
 		( Story ) => (

@@ -30,6 +30,11 @@ const meta: Meta< typeof CustomSelectControl > = {
 		docs: {
 			source: { excludeDecorators: true },
 		},
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+			notes: 'Will be superseded by `SelectControl` in `@wordpress/ui`, but continue using for now.',
+		},
 	},
 	decorators: [
 		( Story ) => (

@@ -25,6 +25,11 @@ const meta: Meta< typeof DateTimePicker > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Consider using a `TextControl` with `type="date"` or `type="datetime-local"` instead.',
+		},
 	},
 };
 export default meta;

@@ -25,6 +25,11 @@ const meta: Meta< typeof DatePicker > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Consider using a `TextControl` with `type="date"` or `type="datetime-local"` instead.',
+		},
 	},
 };
 export default meta;

@@ -25,6 +25,11 @@ const meta: Meta< typeof TimePicker > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Consider using a `TextControl` with `type="date"` or `type="datetime-local"` instead.',
+		},
 	},
 };
 export default meta;

@@ -30,6 +30,10 @@ const meta: Meta< typeof Disabled > = {
 			expanded: true,
 		},
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 

@@ -36,6 +36,11 @@ const meta: Meta< typeof Divider > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'not-recommended',
+			whereUsed: 'global',
+			notes: 'Planned for deprecation.',
+		},
 	},
 };
 export default meta;

@@ -33,6 +33,11 @@ const meta: Meta< typeof Draggable > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { source: { code: '' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'May be deprecated.',
+		},
 	},
 };
 export default meta;

@@ -35,6 +35,10 @@ const meta: Meta< typeof DropZone > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 export default meta;

@@ -30,6 +30,11 @@ const meta: Meta< typeof DropdownMenu > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'When building for the Gutenberg repo, use `Menu` instead. Otherwise, continue using for now.',
+		},
 	},
 	args: {
 		onToggle: fn(),

@@ -41,6 +41,10 @@ const meta: Meta< typeof Dropdown > = {
 		controls: {
 			expanded: true,
 		},
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 export default meta;

@@ -24,6 +24,10 @@ const meta: Meta< typeof DuotonePicker > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'editor',
+		},
 	},
 };
 export default meta;

@@ -14,6 +14,10 @@ const meta: Meta< typeof DuotoneSwatch > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'editor',
+		},
 	},
 };
 export default meta;