Package com.vaadin.flow.component.page

Interface Clipboard

All Superinterfaces:
Serializable
public interface Clipboard extends Serializable
Provides access to the browser Clipboard API.

This interface offers two categories of clipboard operations:

  • Client-side copy (reliable): Methods like copyOnClick(Component, String) set up a click handler that executes the clipboard write directly in the browser event handler, satisfying the user gesture requirement in all browsers.
  • Server-initiated operations: Methods like writeText(String) go through a server round-trip and may not work in Firefox or Safari due to user gesture timeout.

Usage pattern follows WebStorage — static methods that use UI.getCurrentOrThrow() by default.

  • Method Details

    • copyOnClick

      static ClipboardCopy copyOnClick(Component trigger, String text)
      Sets up a client-side click handler on the trigger component that copies the given text to the clipboard when clicked.

      The copy operation executes entirely on the client side within the click event handler, so it satisfies the user gesture requirement in all browsers.

      Parameters:
      trigger - the component whose clicks trigger the copy
      text - the text to copy to the clipboard
      Returns:
      a ClipboardCopy handle for updating the text or removing the handler

    • copyOnClick

      static ClipboardCopy copyOnClick(Component trigger, String text, Command onSuccess, Command onError)
      Sets up a client-side click handler on the trigger component that copies the given text to the clipboard, with success and error callbacks.

      The copy operation executes on the client side. The callbacks are invoked on the server after the clipboard operation completes or fails.

      Parameters:
      trigger - the component whose clicks trigger the copy
      text - the text to copy to the clipboard
      onSuccess - callback invoked on the server when the copy succeeds
      onError - callback invoked on the server when the copy fails
      Returns:
      a ClipboardCopy handle for updating the text or removing the handler

    • copyOnClick

      static ClipboardCopy copyOnClick(Component trigger, Component source)
      Sets up a client-side click handler on the trigger component that copies the current value of the source component to the clipboard.

      The source component's value is read client-side (from the DOM element's value or textContent property) at click time, so no server round-trip is needed.

      Parameters:
      trigger - the component whose clicks trigger the copy
      source - the component whose value to copy
      Returns:
      a ClipboardCopy handle for removing the handler

    • copyImageOnClick

      static ClipboardCopy copyImageOnClick(Component trigger, Component imageSource)
      Sets up a client-side click handler on the trigger component that copies the image from the given image component to the clipboard.

      The image source component should have a src attribute (e.g. an <img> element). The image is fetched client-side from the element's src attribute and written to the clipboard as a blob.

      Parameters:
      trigger - the component whose clicks trigger the copy
      imageSource - the component with a src attribute pointing to an image
      Returns:
      a ClipboardCopy handle for removing the handler

    • writeText

      static PendingJavaScriptResult writeText(String text)
      Writes the given text to the clipboard.

      Browser compatibility note: This method involves a server round-trip and may not work in Firefox or Safari, which require clipboard operations to be performed within a user gesture (click handler call stack). Use copyOnClick(Component, String) for reliable cross-browser clipboard writes.

      Parameters:
      text - the text to write to the clipboard
      Returns:
      a PendingJavaScriptResult for the clipboard operation

    • writeText

      static PendingJavaScriptResult writeText(UI ui, String text)
      Writes the given text to the clipboard using the specified UI.
      Parameters:
      ui - the UI to use
      text - the text to write to the clipboard
      Returns:
      a PendingJavaScriptResult for the clipboard operation

    • writeText

      static void writeText(String text, Command onSuccess, SerializableConsumer<String> onError)
      Writes the given text to the clipboard with success and error callbacks.

      Browser compatibility note: This method involves a server round-trip and may not work in Firefox or Safari.

      Parameters:
      text - the text to write
      onSuccess - callback invoked when the write succeeds
      onError - callback invoked with an error message when the write fails

    • writeText

      static void writeText(UI ui, String text, Command onSuccess, SerializableConsumer<String> onError)
      Writes the given text to the clipboard with success and error callbacks, using the specified UI.
      Parameters:
      ui - the UI to use
      text - the text to write
      onSuccess - callback invoked when the write succeeds
      onError - callback invoked with an error message when the write fails

    • readText

      static void readText(SerializableConsumer<String> callback)
      Reads text from the clipboard.

      Browser compatibility note: This method involves a server round-trip. The browser may prompt the user for permission to read the clipboard.

      Parameters:
      callback - callback invoked with the clipboard text

    • readText

      static void readText(UI ui, SerializableConsumer<String> callback)
      Reads text from the clipboard using the specified UI.
      Parameters:
      ui - the UI to use
      callback - callback invoked with the clipboard text

    • writeImage

      static PendingJavaScriptResult writeImage(String imageUrl)
      Writes an image from the given URL to the clipboard.

      The browser fetches the image from the URL client-side and writes it to the clipboard as a PNG blob.

      Browser compatibility note: This method involves a server round-trip for delivering the JavaScript command.

      Parameters:
      imageUrl - the URL of the image to copy
      Returns:
      a PendingJavaScriptResult for the clipboard operation

    • writeImage

      static PendingJavaScriptResult writeImage(UI ui, String imageUrl)
      Writes an image from the given URL to the clipboard using the specified UI.
      Parameters:
      ui - the UI to use
      imageUrl - the URL of the image to copy
      Returns:
      a PendingJavaScriptResult for the clipboard operation

    • writeImage

      static PendingJavaScriptResult writeImage(StreamResource resource)
      Writes an image from the given StreamResource to the clipboard.

      The stream resource is registered in the session and the browser fetches it client-side.

      Parameters:
      resource - the stream resource providing the image data
      Returns:
      a PendingJavaScriptResult for the clipboard operation

    • writeImage

      static PendingJavaScriptResult writeImage(UI ui, StreamResource resource)
      Writes an image from the given StreamResource to the clipboard using the specified UI.
      Parameters:
      ui - the UI to use
      resource - the stream resource providing the image data
      Returns:
      a PendingJavaScriptResult for the clipboard operation

    • addPasteListener

      static Registration addPasteListener(Component target, SerializableConsumer<ClipboardEvent> listener)
      Adds a listener for paste events on the given component.

      The listener receives text, HTML, and file data from the paste event. Pasted files are transferred to the server via the upload mechanism.

      Parameters:
      target - the component to listen for paste events on
      listener - the paste event listener
      Returns:
      a registration for removing the listener

    • addCopyListener

      static Registration addCopyListener(Component target, SerializableConsumer<ClipboardEvent> listener)
      Adds a listener for copy events on the given component.
      Parameters:
      target - the component to listen for copy events on
      listener - the copy event listener
      Returns:
      a registration for removing the listener

    • addCutListener

      static Registration addCutListener(Component target, SerializableConsumer<ClipboardEvent> listener)
      Adds a listener for cut events on the given component.
      Parameters:
      target - the component to listen for cut events on
      listener - the cut event listener
      Returns:
      a registration for removing the listener