README.md

ImageControl

The ImageControl component allows for selecting a single image from the Media Library in a sidebar panel. Internally, ImageControl is wrapping a MediaUpload inside a BaseControl component.

ImageControl component.

ImageControl component displaying the selected image.

Usage

For a minimum working setup, all you need to do is pass an image ID as value, as well as an onChange callback that accepts an image object.

import { ImageControl } from '@humanmade/block-editor-components';
import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody } from '@wordpress/components';

function BlockEdit( props ) {
	const { attributes, setAttributes } = props;
	const { imageId } = attributes;

	return (
		<InspectorControls>
			<PanelBody>
				<ImageControl
					value={ imageId }
					onChange={ ( image ) => setAttributes( { imageId: image?.id } ) }
				/>
			</PanelBody>
		</InspectorControls>
	);
}

If you want to show a select image size in the sidebar, you can pass a size. In case the image is not available in the specified size, the component will display the full image instead, which is the default behavior.

import { ImageControl } from '@humanmade/block-editor-components';
import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody } from '@wordpress/components';

function BlockEdit( props ) {
	const { attributes, setAttributes } = props;
	const { imageId } = attributes;

	return (
		<InspectorControls>
			<PanelBody>
				<ImageControl
					size="thumbnail"
					value={ imageId }
					onChange={ ( image ) => setAttributes( { imageId: image?.id } ) }
				/>
			</PanelBody>
		</InspectorControls>
	);
}

You can also customize button texts, as well as the modal title.

import { ImageControl } from '@humanmade/block-editor-components';
import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody } from '@wordpress/components';

function BlockEdit( props ) {
	const { attributes, setAttributes } = props;
	const { imageId } = attributes;

	return (
		<InspectorControls>
			<PanelBody>
				<ImageControl
					buttonText="Select Thumbnail"
					modalTitle="Select Thumbnail"
					removeButtonText="Remove thumbnail"
					replaceButtonText="Replace Thumbnail"
					value={ imageId }
					onChange={ ( image ) => setAttributes( { imageId: image?.id } ) }
				/>
			</PanelBody>
		</InspectorControls>
	);
}

Also, all stable props of BaseControl are supported.

Props

The ImageControl component has custom props value and onChange for managing the image, as well as buttonText, modalTitle, removeButtonText and replaceButtonText. Also, it supports all stable props of the BaseControl component.

buttonText

The button text to display if no image has been selected.

Type	Required	Default
string	no	'Select image'

modalTitle

The modal title.

Type	Required	Default
string	no	'Select Image'

onChange

The callback to use for handling changing the image. Please note that onChange will receive an image object from the Media Library.

Type	Required	Default
Function	yes	undefined

removeButtonText

The text to display for the remove button.

Type	Required	Default
string	no	'Remove image'

replaceButtonText

The button text to display if an image has been selected.

Type	Required	Default
string	no	'Replace Image

size

The image size to display in the sidebar.

Type	Required	Default
string	no	undefined

value

An image ID.

Type	Required	Default
number	yes	undefined

Dependencies

The ImageControl component requires the following dependencies, which are expected to be available:

• @wordpress/block-editor
• @wordpress/components
• @wordpress/data
• @wordpress/i18n