Docs
Media

Media

Embed medias like videos or tweets into your document.

Image ElementMedia Embed ElementMedia PopoverMedia Toolbar Button

📸 Image

Add images by either uploading them or providing the image URL:

Customize image captions and resize images.

📺 Embed

Embed various types of content, such as videos and tweets:




Features

  • Allows insertion of embeddable media: images, videos, and tweets.
  • Supports multiple media providers: video, youtube, vimeo, dailymotion, youku, coub, twitter.
  • Editable captions.
  • Resizable.
  • Use Plate Cloud for easy cloud uploads and server-side image resizing.

Installation

npm install @udecode/plate-media

Plugins

import {
  createImagePlugin,
  createMediaEmbedPlugin,
  ELEMENT_IMAGE,
  ELEMENT_MEDIA_EMBED,
} from '@udecode/plate-media';
import { createSelectOnBackspacePlugin } from '@udecode/plate-select';
 
const plugins = [
  // ...otherPlugins,
  createImagePlugin(),
  createMediaEmbedPlugin(),
  createSelectOnBackspacePlugin({
    options: {
      query: {
        allow: [ELEMENT_IMAGE, ELEMENT_MEDIA_EMBED],
      },
    },
  }),
];

API Media

insertMedia

Inserts media (image or media embed) into the editor. The type of media to insert is determined by the type parameter.

Parameters

Collapse all

    The editor instance.

parseMediaUrl

Parses a media URL and returns the data associated with it based on the configured rules of the media plugin.

Parameters

Collapse all

    The editor instance.

submitFloatingMedia

Submits the floating media element by setting its URL and performing necessary transformations.

Parameters

Collapse all

    The editor instance.

MediaPlugin

Common attributes shared by image and media embed plugins.

Attributes

Collapse all

    A function to check whether a text string is a URL.

    A function to transform the URL.

    List of rules. The first rule that matches the URL will be used, i.e. its component will be used to render the media.

    Disables captions for media if set to true.

EmbedUrlData

A type defining the data returned from parsing an embed URL.

Attributes

Collapse all

    The URL of the embedded content.

    The provider of the embedded content.

    The unique ID for the embedded content.

    The component to be rendered for the embedded content.

API Image

createImagePlugin

Options

Collapse all

    Extends MediaPlugin.

    An optional method that will upload the image to a server. The method receives the base64 dataUrl of the uploaded image, and should return the URL of the uploaded image.

    Disables file upload on data insertion if set to true.

    Disables URL embed on data insertion if set to true.

insertImage

Inserts an image element into the editor.

Parameters

Collapse all

    The editor instance.

    The URL or ArrayBuffer of the image.

    Additional options for inserting the image element.

isImageUrl

Checks if a given URL is a valid image URL.

Parameters

Collapse all

    The URL to check.

withImageUpload

Enhances the editor to support pasting images from the clipboard.

Parameters

Collapse all

    The editor instance.

    The plate plugin.

withImageEmbed

Enhances the editor to automatically insert an image when a URL is pasted.

Parameters

Collapse all

    The editor instance.

    The plate plugin.

API Media Embed

createMediaEmbedPlugin

Options extends MediaPlugin.

insertMediaEmbed

Inserts a media embed element at the current selection.

Parameters

Collapse all

    The editor instance.

parseIframeUrl

Parses the URL of an iframe embed.

Parameters

Collapse all

    The URL or embed code of the iframe.

parseTwitterUrl

Parses a Twitter URL and extracts the tweet ID.

Parameters

Collapse all

    The Twitter URL.

Returns

Collapse all

    An object containing the tweet ID and provider if the parsing is successful. Returns undefined if the URL is not valid or does not match any supported video providers.

parseVideoUrl

Parses a video URL and extracts the video ID and provider-specific embed URL.

Parameters

Collapse all

    The video URL.

Returns

Collapse all

    An object containing the video ID and provider if the parsing is successful. Returns undefined if the URL is not valid or does not match any supported video providers.

API Components

useResizable

A behavior hook for resizable elements.

State

Collapse all

    The alignment of the content within the resizable element.

    Specifies whether the resizable element is read-only. If true, the element cannot be resized.

    The minimum width that the resizable element can be adjusted to.

    The maximum width that the resizable element can be adjusted to.

    A function to render the left resize handle. This is typically a component or JSX element.

    A function to render the right resize handle. This is typically a component or JSX element.

    A function to set the width of the node, which is used when resizing.

    A function to set the width of the resizable element directly.

    The current width of the resizable element. This can be a string (e.g., a percentage or 'auto') or a number (representing pixels).

Returns

Collapse all

    A React reference to the outermost div wrapping the resizable element.

    Props to be spread on the outermost div wrapping the resizable element.

    Props to be spread on the resizable element.

    The element to be used as the left handle for resizing. If false, there will be no left handle.

    The element to be used as the right handle for resizing. If false, there will be no right handle.

useFloatingMediaEditButton

A behavior hook for a floating media edit button.

Returns

Collapse all

useFloatingMediaUrlInput

A behavior hook for a floating media URL input.

Props

Collapse all

    The default value for the URL input field.

Returns

Collapse all

useImage

A behavior hook for an image element.

Returns

Collapse all

useMediaEmbed

A behavior hook for a media embed element.

Returns

Collapse all

    The component for rendering the media embed.

    • Default: 'iframe'

useMediaEmbedTweet

A behavior hook for a media embed tweet element.

Props

Collapse all

    The ID of the tweet.

Returns

Collapse all

    An object containing the tweet ID and provider.

useMediaEmbedVideo

A behavior hook for a media embed video element.

Returns

Collapse all

    props.title string

    The title of the embed.

    props.frameBorder string

    The frame border of the embed.

    props.allowFullScreen boolean

    Whether the embed allows fullscreen mode.

useMediaState

A state hook for a media element.

Parameters

Collapse all

Returns

Collapse all

    Whether the media element is currently focused.

    Whether the media element is currently selected.

    Whether the editor is in read-only mode.

    The media provider of the element.

useMediaToolbarButton

A behavior hook for a media toolbar button.

Parameters

Collapse all

Returns

Collapse all

Tweet

A React component for rendering a Tweet.

Props

Collapse all

    The ID of the tweet to embed.

    A callback function that handles errors that occur during the embedding process.

    A callback function that is called when the tweet is successfully loaded.

    A loading component to be rendered while the tweet is being loaded.

    An object that contains options for customizing the embedded tweet.

    • Default: {}
ListMention