Skip to main content
The @wordpress/components package provides a library of generic, reusable UI components for building WordPress interfaces. These components follow WordPress design patterns and are used throughout the block editor.

Installation

npm install @wordpress/components --save

Basic Usage

import { Button } from '@wordpress/components';

export default function MyButton() {
	return <Button variant="primary">Click Me!</Button>;
}

Loading Styles

Components require CSS to display correctly: In WordPress:
wp_enqueue_style( 'wp-components' );
In other projects:
import '@wordpress/components/build-style/style.css';

Common Components

Button

Clickable button component.
import { Button } from '@wordpress/components';

<Button
	variant="primary"
	onClick={ handleClick }
	isBusy={ isLoading }
>
	Save Changes
</Button>
Variants:
  • primary - Primary action button
  • secondary - Secondary action button
  • tertiary - Tertiary/text button
  • link - Link-style button

Panel

Collapsible panel container.
import { Panel, PanelBody, PanelRow } from '@wordpress/components';

<Panel>
	<PanelBody title="Settings" initialOpen={ true }>
		<PanelRow>
			{ /* Panel content */ }
		</PanelRow>
	</PanelBody>
</Panel>

TextControl

Text input field.
import { TextControl } from '@wordpress/components';

<TextControl
	label="Name"
	value={ name }
	onChange={ ( value ) => setName( value ) }
	help="Enter your name"
/>

TextareaControl

Multi-line text input.
import { TextareaControl } from '@wordpress/components';

<TextareaControl
	label="Description"
	value={ description }
	onChange={ ( value ) => setDescription( value ) }
	rows={ 4 }
/>

SelectControl

Dropdown select field.
import { SelectControl } from '@wordpress/components';

<SelectControl
	label="Size"
	value={ size }
	options={ [
		{ label: 'Small', value: 'small' },
		{ label: 'Medium', value: 'medium' },
		{ label: 'Large', value: 'large' },
	] }
	onChange={ ( value ) => setSize( value ) }
/>

CheckboxControl

Checkbox input.
import { CheckboxControl } from '@wordpress/components';

<CheckboxControl
	label="Enable feature"
	checked={ isEnabled }
	onChange={ ( checked ) => setEnabled( checked ) }
/>

ToggleControl

Toggle switch.
import { ToggleControl } from '@wordpress/components';

<ToggleControl
	label="Dark Mode"
	checked={ isDarkMode }
	onChange={ ( checked ) => setDarkMode( checked ) }
/>

RadioControl

Radio button group.
import { RadioControl } from '@wordpress/components';

<RadioControl
	label="Alignment"
	selected={ alignment }
	options={ [
		{ label: 'Left', value: 'left' },
		{ label: 'Center', value: 'center' },
		{ label: 'Right', value: 'right' },
	] }
	onChange={ ( value ) => setAlignment( value ) }
/>

RangeControl

Numeric range slider.
import { RangeControl } from '@wordpress/components';

<RangeControl
	label="Opacity"
	value={ opacity }
	onChange={ ( value ) => setOpacity( value ) }
	min={ 0 }
	max={ 100 }
/>

Layout Components

Card

Card container with header and content.
import { Card, CardHeader, CardBody } from '@wordpress/components';

<Card>
	<CardHeader>Card Title</CardHeader>
	<CardBody>
		Card content goes here
	</CardBody>
</Card>
Dialog modal overlay.
import { Modal, Button } from '@wordpress/components';
import { useState } from '@wordpress/element';

function MyComponent() {
	const [ isOpen, setIsOpen ] = useState( false );

	return (
		<>
			<Button onClick={ () => setIsOpen( true ) }>
				Open Modal
			</Button>
			{ isOpen && (
				<Modal
					title="Modal Title"
					onRequestClose={ () => setIsOpen( false ) }
				>
					<p>Modal content</p>
				</Modal>
			) }
		</>
	);
}

Popover

Floating popover element.
import { Popover, Button } from '@wordpress/components';
import { useState } from '@wordpress/element';

function MyComponent() {
	const [ isVisible, setIsVisible ] = useState( false );

	return (
		<>
			<Button onClick={ () => setIsVisible( ! isVisible ) }>
				Toggle Popover
			</Button>
			{ isVisible && (
				<Popover onClose={ () => setIsVisible( false ) }>
					<div>Popover content</div>
				</Popover>
			) }
		</>
	);
}
Dropdown menu.
import { Dropdown, Button, MenuGroup, MenuItem } from '@wordpress/components';

<Dropdown
	renderToggle={ ( { isOpen, onToggle } ) => (
		<Button onClick={ onToggle } aria-expanded={ isOpen }>
			Menu
		</Button>
	) }
	renderContent={ () => (
		<MenuGroup>
			<MenuItem onClick={ handleAction1 }>Action 1</MenuItem>
			<MenuItem onClick={ handleAction2 }>Action 2</MenuItem>
		</MenuGroup>
	) }
/>

TabPanel

Tabbed interface.
import { TabPanel } from '@wordpress/components';

<TabPanel
	tabs={ [
		{ name: 'tab1', title: 'Tab 1' },
		{ name: 'tab2', title: 'Tab 2' },
	] }
>
	{ ( tab ) => <p>Content for { tab.name }</p> }
</TabPanel>
Keyboard-navigable menu.
import { NavigableMenu, MenuItem } from '@wordpress/components';

<NavigableMenu>
	<MenuItem onClick={ handleItem1 }>Item 1</MenuItem>
	<MenuItem onClick={ handleItem2 }>Item 2</MenuItem>
</NavigableMenu>

Advanced Components

ColorPicker

Color selection interface.
import { ColorPicker } from '@wordpress/components';

<ColorPicker
	color={ color }
	onChangeComplete={ ( value ) => setColor( value.hex ) }
/>

DateTimePicker

Date and time selection.
import { DateTimePicker } from '@wordpress/components';

<DateTimePicker
	currentDate={ date }
	onChange={ ( newDate ) => setDate( newDate ) }
/>

TreeSelect

Hierarchical select dropdown.
import { TreeSelect } from '@wordpress/components';

<TreeSelect
	label="Category"
	tree={ categoryTree }
	selectedId={ selectedCategory }
	onChange={ ( id ) => setSelectedCategory( id ) }
/>

Notification Components

Notice

Inline notification message.
import { Notice } from '@wordpress/components';

<Notice status="success" onRemove={ handleDismiss }>
	Changes saved successfully!
</Notice>
Status options:
  • success
  • error
  • warning
  • info

Snackbar

Temporary notification toast.
import { Snackbar } from '@wordpress/components';

<Snackbar onDismiss={ handleDismiss }>
	Action completed
</Snackbar>

Utility Components

Spinner

Loading indicator.
import { Spinner } from '@wordpress/components';

<Spinner />

Placeholder

Empty state placeholder.
import { Placeholder, Button } from '@wordpress/components';

<Placeholder
	icon="admin-post"
	label="No content"
	instructions="Get started by adding content"
>
	<Button variant="primary">Add Content</Button>
</Placeholder>

Icon

Icon display component.
import { Icon } from '@wordpress/components';
import { wordpress } from '@wordpress/icons';

<Icon icon={ wordpress } size={ 24 } />

Using Popovers

When using Popover components, include the Popover.Slot:
import { Popover, SlotFillProvider } from '@wordpress/components';

function App() {
	return (
		<SlotFillProvider>
			<MyComponentWithPopover />
			<Popover.Slot />
		</SlotFillProvider>
	);
}

TypeScript

Extract props types using React’s ComponentProps:
import type { ComponentProps } from 'react';
import { Button } from '@wordpress/components';

function MyButton( props: ComponentProps< typeof Button > ) {
	return <Button { ...props }>Click Me!</Button>;
}

Learn More

Build docs developers (and LLMs) love