MediaSuiteCaption (experimental)

Display and edit media captions

The MediaSuiteCaption component is used to display and optionally edit media captions. It can be used on its own or together with other media components.

The caption is rendered inside a <figcaption> element and should therefore be placed within a <figure> tag. If no caption is provided, MediaSuiteCaption will automatically fetch and display the caption from the media library based on the mediaId.

link Standalone example, no editing

You can use MediaSuiteCaption to simply display a caption without editing. In this mode, the caption is shown only if one is provided or if the media library contains a caption for the given mediaId. If you omit the mediaId, no caption will be fetched from the media library.

import { __experimentalMediaSuiteCaption as MediaSuiteCaption, useBasicMedia } from '@t2/editor';
import { useBlockProps } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';

export default function Edit({ attributes }) {
	const { mediaId, mediaUrl, mediaType, caption } = attributes;
	const blockProps = useBlockProps({ className: 't2-test-block' });

	// Get the basic media details.
	const { basic } = useBasicMedia(mediaId, mediaUrl, mediaType);

	return (
		<div {...blockProps}>
			<p>{__('This is a simple test block with an image.', 't2')}</p>
			<figure style={ { marginBlockEnd: 0 }}>
				<img src={basic.url} alt={basic.alt} style={ { aspectRatio: '2', display: 'block' }} />
				<MediaSuiteCaption caption={caption} mediaId={basic.id} />
			</figure>
		</div>
	);
}

link Standalone example, with editing enabled

Caption editing is enabled by supplying an onCaptionChange callback. This callback receives two arguments: the new caption value and a boolean indicating whether the caption should be shown (true) or hidden (false).

If the provided caption differs from the media library caption, a reset icon will appear, allowing users to revert to the original caption. You can disable this icon by setting the showCaptionReset prop to false.

import { __experimentalMediaSuiteCaption as MediaSuiteCaption, useBasicMedia } from '@t2/editor';
import { useBlockProps } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';

export default function Edit({ attributes, setAttributes }) {
    const { mediaId, mediaUrl, mediaType, caption, showMediaCaption } = attributes;
    const blockProps = useBlockProps({ className: 't2-test-block' });

    // Get the basic media details.
    const { basic } = useBasicMedia(mediaId, mediaUrl, mediaType);

    return (
        <div {...blockProps}>
            <p>{__('This is a simple test block with an image.', 't2')}</p>
            <figure style={ { marginBlockEnd: 0 }}>
                <img src={basic.url} alt={basic.alt} style={ { aspectRatio: '2', display: 'block' }} />
                <MediaSuiteCaption
                    caption={caption}
                    mediaId={basic.id}
                    showMediaCaption={showMediaCaption}
                    onCaptionChange={(value, show) => setAttributes({ caption: value, showMediaCaption: show })}
                />
            </figure>
        </div>
    );
}

link Integration with MediaSuiteViewer

You can integrate MediaSuiteCaption into the MediaSuiteViewer using the renderMediaCaption callback — with or without editing enabled. In the example below, editing is enabled.

import {
    __experimentalMediaSuiteViewer as MediaSuiteViewer,
    __experimentalMediaSuiteCaption as MediaSuiteCaption,
} from '@t2/editor';
import { useBlockProps } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';

export default function Edit({ attributes, setAttributes }) {
    const { mediaId, mediaUrl, mediaType, caption, showMediaCaption } = attributes;
    const blockProps = useBlockProps({ className: 't2-test-block' });

    return (
        <div {...blockProps}>
            <p>{__('This is a simple test block with an image.', 't2')}</p>
            <MediaSuiteViewer
                mediaId={mediaId}
                mediaUrl={mediaUrl}
                mediaType={mediaType}
                renderMediaCaption={(viewerProps) => (
                    <MediaSuiteCaption
                        caption={caption}
                        mediaId={viewerProps.mediaId}
                        showMediaCaption={showMediaCaption}
                        onCaptionChange={(value, show) => setAttributes({ caption: value, showMediaCaption: show })}
                    />
                )}
            />
        </div>
    );
}

link MediaSuiteCaption properties

export type MediaSuiteCaptionProps = HTMLProps<HTMLElement> & {
    /** The caption text to display. */
    caption: string | undefined;

    /** The media (attachment) ID used to fetch the caption from the media library. */
    mediaId?: number;

    /** Controls whether the media caption is shown (default: true). */
    showMediaCaption?: boolean;

    /** Controls whether the toolbar includes a toggle for showing/hiding the caption (default: true). */
    showCaptionToggle?: boolean;

    /** Controls whether a reset icon is shown to restore the original media library caption (default: true). */
    showCaptionReset?: boolean;

    /** Callback fired when either the caption text or its visibility changes. */
    onCaptionChange?: (caption: string | undefined, showCaption: boolean) => void;
};