Package com.vaadin.flow.component.clipboard

Class Clipboard

java.lang.Object
com.vaadin.flow.component.clipboard.Clipboard
All Implemented Interfaces:
Serializable
public final class Clipboard extends Object implements Serializable
Entry point for the browser clipboard API. Bind clipboard actions to a user gesture by chaining off onClick(Component): 

 Button copyButton = new Button("Copy");
 Clipboard.onClick(copyButton).writeText(textField);

 Clipboard.onClick(copyButton)
         .write(ClipboardContent.create().text("Hello").html("<b>Hello</b>"));
The Clipboard API requires a fresh user gesture for each write, so actions only run during the DOM event that fires the underlying trigger.

Read-side support is exposed through onPaste, which forwards the browser's native paste event to a server-side listener as a PasteEvent. Unlike the write API, onPaste does not need a click binding — it attaches a DOM listener directly to the given component and fires on every paste gesture targeting it (or any of its descendants, since paste bubbles). Pass the UI as the component for UI-wide scope; the options overload lets the application skip pastes whose target is a form field — useful for page-wide listeners that should only react to pastes intended for the page as a whole.

File pastes (screenshots, files dragged in from the OS, anything that surfaces as event.clipboardData.files) are handled by a dedicated read-side API, onFilePaste. Each pasted file becomes its own upload — one fetch POST per file, addressed to the URL generated for the supplied UploadHandler — and the handler's own per-file callback (in-memory, file, temp file) is what the application implements. For paste-aware orchestration, pair with PasteFileHandler: inMemory for a per-file callback that flags the first file of each paste, or session() for a three-step listener (onStart/onFile/onComplete) that knows when the whole paste has finished delivering. Use a raw UploadHandler when neither shape fits. onFilePaste is independent of onPaste; the same paste gesture can deliver text/html via onPaste and files via onFilePaste when both are registered.

See Also:

  • Field Details

    • PASTE_ID_HEADER

      public static final String PASTE_ID_HEADER
      Request header set by the client-side paste-upload helper on every fetch POST that originates from a paste gesture. The value is a monotonically increasing sequence number (as decimal text) so server handlers can correlate the parallel uploads of one paste and tell pastes apart from each other. Two distinct pastes in the same browser tab always carry strictly increasing values; pastes from different tabs are not comparable.

      Raw UploadHandler implementations may read this header directly via event.getRequest().getHeader(PASTE_ID_HEADER); PasteFileHandler.inMemory(SerializableConsumer) reads it for the caller and exposes it as PasteFile.pasteId().

      See Also:

    • PASTE_FILE_COUNT_HEADER

      public static final String PASTE_FILE_COUNT_HEADER
      Request header set alongside PASTE_ID_HEADER carrying the total number of files in the originating paste. The session-style handler built by PasteFileHandler.session() uses it to fire onComplete once the server has observed all files of a paste — without it the server has no way to tell mid-paste arrival from "all done".
      See Also:

  • Method Details

    • onClick

      public static <T extends Component & ClickNotifier<?>> ClipboardBinding onClick(T component)
      Registers the given component as a clickable trigger for a clipboard action — the common shape for copy-to-clipboard buttons. Equivalent to new ClickTrigger(component), without making callers reach for the trigger framework's internal types.
      Type Parameters:
      T - the component type, must implement ClickNotifier
      Parameters:
      component - the component to listen for clicks on, not null
      Returns:
      a new binding that can chain actions to this trigger

    • onPaste

      public static Registration onPaste(Component component, SerializableConsumer<PasteEvent> listener)
      Registers a listener for browser paste events on the given component. The listener is invoked on the UI thread once per paste gesture targeting component (or any descendant, since paste bubbles) with a PasteEvent carrying the text/plain and text/html representations of the pasted content.

      The browser only fires paste when the target element is focused at the moment the user invokes paste. For non-editable elements such as a Div this means the element must be made focusable, typically via tabindex="0". See PasteEvent for the rest of the browser caveats.

      Example: 

      
 Div pasteTarget = new Div();
 pasteTarget.getElement().setAttribute("tabindex", "0");
 add(pasteTarget);

 Clipboard.onPaste(pasteTarget, event -> {
     if (event.hasHtml()) {
         renderHtml(event.getHtml());
     } else if (event.hasText()) {
         renderText(event.getText());
     }
 });
      Parameters:
      component - the component to listen for paste events on, not null
      listener - the listener invoked for each paste, not null
      Returns:
      a Registration whose remove detaches the paste listener

    • onPaste

      public static Registration onPaste(Component component, PasteOptions options, SerializableConsumer<PasteEvent> listener)
      Registers a listener for browser paste events on the given component with the given PasteOptions. The listener is invoked on the UI thread for each paste gesture targeting component (or any descendant, since paste bubbles) whose target matches the options. For UI-wide scope, pass the UI as the component; the UI's root element is <body> so it receives every paste event that bubbles up from anywhere on the page.

      The component does not need to be attached at registration time — the underlying DOM listener is bound to the component's element and is applied when the element is attached to a UI.

      Pass PasteOptions.defaults() to skip pastes whose target is an input, textarea, or contenteditable element (typically what a page-wide listener wants). Pass PasteOptions.includingInputFields() to observe every paste regardless of focus.

      Parameters:
      component - the component to listen for paste events on, not null
      options - paste filtering options, not null
      listener - the listener invoked for each matching paste, not null
      Returns:
      a Registration whose remove detaches the paste listener

    • onFilePaste

      public static Registration onFilePaste(Component component, UploadHandler handler)
      Registers a file-upload listener for browser paste events on the given component. When a paste delivers files (a screenshot from the OS clipboard, files copied from a file manager, anything that arrives on event.clipboardData.files) each file is uploaded to the URL generated for handler; the handler's own per-file callback then runs server-side, exactly as for a regular upload. Pastes without files are ignored.

      One XHR is sent per file, matching the wire format used by vaadin-upload: the file is the request body, the file name travels in the X-Filename header (percent-encoded), and the file's MIME type goes in Content-Type. The supplied UploadHandler's configured per-file size limit therefore applies unchanged.

      Unlike onPaste, the file variant does not offer an "ignore pastes into form fields" option: browsers never paste files into an <input> or <textarea>, so there is no native paste behaviour to compete with, and a paste containing a file in a focused text field is still a "the user dropped a file on the page" event from the application's point of view.

      This API is independent of onPaste. A paste that carries both files and text fires both listeners when both are registered.

      Example: 

      
 Clipboard.onFilePaste(this, UploadHandler.inMemory((meta, bytes) -> {
     store(meta.fileName(), bytes);
 }));
      Parameters:
      component - the component to listen for paste events on, not null
      handler - the upload handler invoked per pasted file, not null
      Returns:
      a Registration whose remove detaches the paste listener and discards the per-registration upload URL