Status: stable

A simple horizontal progress bar component.

Supports two modes: determinate and indeterminate. A progress bar is determinate when a specific progress value has been specified (from 0 to 100), and indeterminate when a value hasn’t been specified.

View on Storybook

View source on GitHub

Import

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

Examples

Default

const Default = () => {
    return <ProgressBar />;
};

With Custom Width

A progress bar with a custom width. You can override the default width by passing a custom CSS class via the className prop. This example shows a progress bar with an overridden width of 100% which makes it fit all available horizontal space of the parent element. The CSS class looks like this: css .custom-progress-bar { width: 100%; }

const WithCustomWidth = () => {
    return <ProgressBar className="custom-progress-bar" />;
};

Highlights occurrences of a given string within another string of text. Wraps each match with a <mark> tag which provides browser default styling.

View on Storybook

View source on GitHub

Import

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

Props

Examples

Default

const Default = () => {
    return (
        <TextHighlight
            text="We call the new editor Gutenberg. The entire editing experience has been rebuilt for media rich pages and posts."
            highlight="Gutenberg" />
    );
};

Render a user interface to select the user type using radio inputs.

View on Storybook

View source on GitHub

Import

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

Examples

Default

const Default = () => {
    const [ value, setValue ] = useState( options?.[ 0 ]?.value );

    return (
        <RadioControl
            label="Post visibility"
            selected={ value }
            options={ options }
            onChange={ ( v ) => {
				setValue( v );
				onChange( v );
			} } />
    );
};

With Option Descriptions

const WithOptionDescriptions = () => {
    const [ value, setValue ] = useState( options?.[ 0 ]?.value );

    return (
        <RadioControl
            selected={ value }
            options={ options }
            onChange={ ( v ) => {
				setValue( v );
				onChange( v );
			} } />
    );
};

ToggleControl is used to generate a toggle user interface.

View on Storybook

View source on GitHub

Import

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

Examples

Default

const Default = ( {
	onChange,
	...props
} ) => {
	const [ checked, setChecked ] = useState( true );
	return (
		<ToggleControl
			{ ...props }
			checked={ checked }
			onChange={ ( ...changeArgs ) => {
				setChecked( ...changeArgs );
				onChange( ...changeArgs );
			} }
		/>
	);
};

With Help Text

const WithHelpText = ( {
	onChange,
	...props
} ) => {
	const [ checked, setChecked ] = useState( true );
	return (
		<ToggleControl
			{ ...props }
			checked={ checked }
			onChange={ ( ...changeArgs ) => {
				setChecked( ...changeArgs );
				onChange( ...changeArgs );
			} }
		/>
	);
};

RangeControls are used to make selections from a range of incremental values.

View on Storybook

View source on GitHub

Import

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

Examples

Default

const Default = () => {
    const [ value, setValue ] = useState< number >();

    return (
        <RangeControl
            __next40pxDefaultSize
            onBlur={fn()}
            onFocus={fn()}
            onMouseLeave={fn()}
            onMouseMove={fn()}
            help="Please select how transparent you would like this."
            initialPosition={50}
            label="Opacity"
            max={100}
            min={0}
            value={ value }
            onChange={ ( v ) => {
				setValue( v );
				onChange?.( v );
			} } />
    );
};

With Any Step

Setting the step prop to "any" will allow users to select non-integer values. This also overrides both withInputField and showTooltip props to false.

const WithAnyStep = () => {
    const [ value, setValue ] = useState< number >();

    return (
        <>
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                label="Brightness"
                step="any"
                value={ value }
                onChange={ ( v ) => {
					setValue( v );
					onChange?.( v );
				} } />
            <hr style={ { marginTop: '5em' } } />
            <p>Current value: { value }</p>
        </>
    );
};

With Integer Step And Marks

Use marks to render a visual representation of step ticks. Marks may be automatically generated or custom mark indicators can be provided by an Array.

const WithIntegerStepAndMarks = () => {
    const [ automaticValue, setAutomaticValue ] = useState< number >();
    const [ customValue, setCustomValue ] = useState< number >();

    return (
        <>
            <h2>{ label }</h2>
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                max={10}
                min={0}
                step={1}
                label="Automatic marks"
                marks
                onChange={ ( v ) => {
					setAutomaticValue( v );
					onChange?.( v );
				} }
                value={ automaticValue } />
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                marks={marksBase}
                max={10}
                min={0}
                step={1}
                label="Custom marks"
                onChange={ ( v ) => {
					setCustomValue( v );
					onChange?.( v );
				} }
                value={ customValue } />
        </>
    );
};

With Decimal Step And Marks

Decimal values may be used for marks rendered as a visual representation of step ticks. Marks may be automatically generated or custom mark indicators can be provided by an Array.

const WithDecimalStepAndMarks = () => {
    const [ automaticValue, setAutomaticValue ] = useState< number >();
    const [ customValue, setCustomValue ] = useState< number >();

    return (
        <>
            <h2>{ label }</h2>
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                max={10}
                min={0}
                step={0.1}
                label="Automatic marks"
                marks
                onChange={ ( v ) => {
					setAutomaticValue( v );
					onChange?.( v );
				} }
                value={ automaticValue } />
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                marks={[
                    ...marksBase,
                    { value: 3.5, label: '3.5' },
                    { value: 5.8, label: '5.8' },
                ]}
                max={10}
                min={0}
                step={0.1}
                label="Custom marks"
                onChange={ ( v ) => {
					setCustomValue( v );
					onChange?.( v );
				} }
                value={ customValue } />
        </>
    );
};

With Negative Minimum And Marks

A negative min value can be used to constrain RangeControl values. Mark indicators can represent negative values as well. Marks may be automatically generated or custom mark indicators can be provided by an Array.

const WithNegativeMinimumAndMarks = () => {
    const [ automaticValue, setAutomaticValue ] = useState< number >();
    const [ customValue, setCustomValue ] = useState< number >();

    return (
        <>
            <h2>{ label }</h2>
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                max={10}
                min={-10}
                step={1}
                label="Automatic marks"
                marks
                onChange={ ( v ) => {
					setAutomaticValue( v );
					onChange?.( v );
				} }
                value={ automaticValue } />
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                marks={marksWithNegatives}
                max={10}
                min={-10}
                step={1}
                label="Custom marks"
                onChange={ ( v ) => {
					setCustomValue( v );
					onChange?.( v );
				} }
                value={ customValue } />
        </>
    );
};

With Negative Range And Marks

The entire range of valid values for a RangeControl may be negative. Mark indicators can represent negative values as well. Marks may be automatically generated or custom mark indicators can be provided by an Array.

const WithNegativeRangeAndMarks = () => {
    const [ automaticValue, setAutomaticValue ] = useState< number >();
    const [ customValue, setCustomValue ] = useState< number >();

    return (
        <>
            <h2>{ label }</h2>
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                max={-1}
                min={-10}
                step={1}
                label="Automatic marks"
                marks
                onChange={ ( v ) => {
					setAutomaticValue( v );
					onChange?.( v );
				} }
                value={ automaticValue } />
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                marks={marksWithNegatives}
                max={-1}
                min={-10}
                step={1}
                label="Custom marks"
                onChange={ ( v ) => {
					setCustomValue( v );
					onChange?.( v );
				} }
                value={ customValue } />
        </>
    );
};

With Any Step And Marks

When a RangeControl has a step value of any a user may select non-integer values. This may still be used in conjunction with marks rendering a visual representation of step ticks.

const WithAnyStepAndMarks = () => {
    const [ automaticValue, setAutomaticValue ] = useState< number >();
    const [ customValue, setCustomValue ] = useState< number >();

    return (
        <>
            <h2>{ label }</h2>
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                max={10}
                min={0}
                step="any"
                label="Automatic marks"
                marks
                onChange={ ( v ) => {
					setAutomaticValue( v );
					onChange?.( v );
				} }
                value={ automaticValue } />
            <RangeControl
                __next40pxDefaultSize
                onBlur={fn()}
                onFocus={fn()}
                onMouseLeave={fn()}
                onMouseMove={fn()}
                marks={marksBase}
                max={10}
                min={0}
                step="any"
                label="Custom marks"
                onChange={ ( v ) => {
					setCustomValue( v );
					onChange?.( v );
				} }
                value={ customValue } />
        </>
    );
};

View on Storybook

View source on GitHub

Import

import { __experimentalToggleGroupControl as ToggleGroupControl } from '@wordpress/components';

Examples

Default

const Default = ( {
	onChange,
	...props
} ) => {
	const [ value, setValue ] =
		useState< ToggleGroupControlProps[ 'value' ] >();

	return (
		<ToggleGroupControl
			__next40pxDefaultSize
			{ ...props }
			onChange={ ( ...changeArgs ) => {
				setValue( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
			value={ value }
		/>
	);
};

With Tooltip

A tooltip can be shown for each option by enabling the showTooltip prop. The aria-label will be used in the tooltip if provided. Otherwise, the label will be used.

const WithTooltip = ( {
	onChange,
	...props
} ) => {
	const [ value, setValue ] =
		useState< ToggleGroupControlProps[ 'value' ] >();

	return (
		<ToggleGroupControl
			__next40pxDefaultSize
			{ ...props }
			onChange={ ( ...changeArgs ) => {
				setValue( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
			value={ value }
		/>
	);
};

With Icons

The ToggleGroupControlOptionIcon component can be used for icon options. A label is required on each option for accessibility, which will be shown in a tooltip.

const WithIcons = ( {
	onChange,
	...props
} ) => {
	const [ value, setValue ] =
		useState< ToggleGroupControlProps[ 'value' ] >();

	return (
		<ToggleGroupControl
			__next40pxDefaultSize
			{ ...props }
			onChange={ ( ...changeArgs ) => {
				setValue( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
			value={ value }
		/>
	);
};

Deselectable

When the isDeselectable prop is true, the option can be deselected by clicking on it again.

const Deselectable = ( {
	onChange,
	...props
} ) => {
	const [ value, setValue ] =
		useState< ToggleGroupControlProps[ 'value' ] >();

	return (
		<ToggleGroupControl
			__next40pxDefaultSize
			{ ...props }
			onChange={ ( ...changeArgs ) => {
				setValue( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
			value={ value }
		/>
	);
};

View on Storybook

View source on GitHub

Import

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

Props

Examples

Default

const Default = ( {
	onResizeStop,
	...props
} ) => {
	const [ { height, width }, setAttributes ] = useState( {
		height: 200,
		width: 400,
	} );

	return (
		<ResizableBox
			{ ...props }
			size={ {
				height,
				width,
			} }
			onResizeStop={ ( event, direction, elt, delta ) => {
				onResizeStop?.( event, direction, elt, delta );
				setAttributes( {
					height: height + delta.height,
					width: width + delta.width,
				} );
			} }
		/>
	);
};

Disabled Directions

The enable prop can be used to disable resizing in specific directions.

const DisabledDirections = ( {
	onResizeStop,
	...props
} ) => {
	const [ { height, width }, setAttributes ] = useState( {
		height: 200,
		width: 400,
	} );

	return (
		<ResizableBox
			{ ...props }
			size={ {
				height,
				width,
			} }
			onResizeStop={ ( event, direction, elt, delta ) => {
				onResizeStop?.( event, direction, elt, delta );
				setAttributes( {
					height: height + delta.height,
					width: width + delta.width,
				} );
			} }
		/>
	);
};

View on Storybook

View source on GitHub

Import

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

Props

Examples

Default

const Default = ( props ) => (
	<Tooltip { ...props } />
);

Keyboard Shortcut

const KeyboardShortcut = ( props ) => (
	<Tooltip { ...props } />
);

Nested

In case one or more Tooltip components are rendered inside another Tooltip component, only the tooltip associated to the outermost Tooltip component will be rendered in the browser and shown to the user appropriately. The rest of the nested Tooltip components will simply no-op and pass-through their anchor.

const Nested = ( props ) => (
	<Tooltip { ...props } />
);

This component provides an isolated environment for arbitrary HTML via iframes.

View on Storybook

View source on GitHub

Import

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

Props

Examples

Default

const Default = () => <SandBox onFocus={fn()} html="<p>Arbitrary HTML content</p>" />;

TreeGrid is used to create a tree hierarchy. It is not a visually styled component, but instead helps with adding keyboard navigation and roving tab index behaviors to tree grid structures.

A tree grid is a hierarchical 2 dimensional UI component, for example it could be used to implement a file system browser.

A tree grid allows the user to navigate using arrow keys. Up/down to navigate vertically across rows, and left/right to navigate horizontally between focusables in a row.

The TreeGrid renders both a table and tbody element, and is intended to be used with TreeGridRow (tr) and TreeGridCell (td) to build out a grid.

@see {@link https://www.w3.org/TR/wai-aria-practices/examples/treegrid/treegrid-1.html}

View on Storybook

View source on GitHub

Import

import { __experimentalTreeGrid as TreeGrid } from '@wordpress/components';

Props

Examples

Default

const Default = () => <TreeGrid onExpandRow={fn()} onCollapseRow={fn()} onFocusRow={fn()}><Rows items={ groceries } /></TreeGrid>;