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
Browser clipboard API for Flow applications. Two categories of operations: Use availabilityHintSignal() to detect whether the API is usable in the current page context — typically to hide clipboard controls on pages served over plain HTTP.

Click-to-copy example: 

 Button copy = new Button("Copy link");
 Clipboard.copyOnClick(copy, "https://example.com/share/abc123");

Paste-listener example: 

 Clipboard.addPasteListener(textArea, event -> {
     if (event.hasHtml()) {
         editor.setHtmlContent(sanitize(event.getHtml()));
     } else if (event.hasText()) {
         editor.setTextContent(event.getText());
     }
     for (ClipboardFile file : event.getFiles()) {
         saveAttachment(file.getName(), file.getMimeType(), file.getData());
     }
 });

Availability example: 

 Signal.effect(this, () -> {
     boolean usable = Clipboard.availabilityHintSignal()
             .get() == ClipboardAvailability.AVAILABLE;
     copyButton.setVisible(usable);
 });
See Also:

  • Method Details

    • copyOnClick

      public static ClipboardCopy copyOnClick(Component trigger, String text)
      Installs a client-side click handler on trigger that copies text to the clipboard. The copy executes inside the click handler so the browser's user-gesture check is satisfied in all supported browsers.

      The text can be updated later via ClipboardCopy.setValue(String) without a server round-trip on click. To remove the handler, call ClipboardCopy.remove().

      Parameters:
      trigger - the component whose clicks trigger the copy, not null
      text - the text to copy; null is treated as an empty string
      Returns:
      a handle for updating the value or removing the handler
      Throws:
      NullPointerException - if trigger is null

    • copyOnClick

      public static ClipboardCopy copyOnClick(Component trigger, String text, @Nullable Command onSuccess, @Nullable Command onError)
      Like copyOnClick(Component, String) but with server-side callbacks invoked when the browser reports success or failure of the clipboard write.

      The success callback fires after the browser resolves the navigator.clipboard.writeText promise; the error callback fires if the promise rejects (e.g. the user denied permission or the document is not focused).

      Parameters:
      trigger - the component whose clicks trigger the copy, not null
      text - the text to copy; null is treated as an empty string
      onSuccess - invoked on the UI thread when the write succeeds, or null for no-op
      onError - invoked on the UI thread when the write fails, or null for no-op
      Returns:
      a handle for updating the value or removing the handler
      Throws:
      NullPointerException - if trigger is null

    • copyOnClick

      public static ClipboardCopy copyOnClick(Component trigger, Component source)
      Installs a click handler on trigger that copies the current value of source on each click. The value is read live from the source element on the client side: the value property is used if present (input / textarea / Vaadin field components), otherwise textContent.

      Use this to wire a "copy" button next to a text field — clicks always copy the field's current value without a server round-trip.

      Parameters:
      trigger - the component whose clicks trigger the copy, not null
      source - the component whose value to copy, not null
      Returns:
      a handle for removing the handler
      Throws:
      NullPointerException - if trigger or source is null

    • copyOnClick

      public static ClipboardCopy copyOnClick(Component trigger, Component source, @Nullable Command onSuccess, @Nullable Command onError)
      Like copyOnClick(Component, Component) but with server-side callbacks invoked when the browser reports success or failure of the clipboard write. The source's value is still read live on each click — only the success / error notification is added.
      Parameters:
      trigger - the component whose clicks trigger the copy, not null
      source - the component whose value to copy, not null
      onSuccess - invoked on the UI thread when the write succeeds, or null for no-op
      onError - invoked on the UI thread when the write fails, or null for no-op
      Returns:
      a handle for removing the handler
      Throws:
      NullPointerException - if trigger or source is null

    • copyImageOnClick

      public static ClipboardCopy copyImageOnClick(Component trigger, Component imageSource)
      Installs a click handler on trigger that copies the image referenced by imageSource to the clipboard. The image's src attribute is fetched on the client side and written to the clipboard as the original blob's MIME type.

      If the source's blob type is not one the browser accepts on the clipboard (currently only image/png on most browsers), the write may fail; subscribe to availability if you need to gate the control. The image must be reachable from the browser's same-origin policy or served with a CORS header that permits the page's origin — otherwise the fetch will fail.

      Parameters:
      trigger - the component whose clicks trigger the copy, not null
      imageSource - the component carrying the image src (typically an <img>), not null
      Returns:
      a handle for removing the handler
      Throws:
      NullPointerException - if trigger or imageSource is null

    • copyImageOnClick

      public static ClipboardCopy copyImageOnClick(Component trigger, Component imageSource, @Nullable Command onSuccess, @Nullable Command onError)
      Like copyImageOnClick(Component, Component) but with server-side callbacks invoked when the browser reports success or failure of the clipboard write. The error callback fires for any step in the pipeline (image fetch, blob conversion, clipboard write) — the failure is not distinguished by stage.
      Parameters:
      trigger - the component whose clicks trigger the copy, not null
      imageSource - the component carrying the image src, not null
      onSuccess - invoked on the UI thread when the write succeeds, or null for no-op
      onError - invoked on the UI thread when the write fails, or null for no-op
      Returns:
      a handle for removing the handler
      Throws:
      NullPointerException - if trigger or imageSource is null

    • addPasteListener

      public static Registration addPasteListener(Component target, SerializableConsumer<ClipboardEvent> listener)
      Adds a paste listener to target. Each pasted file is buffered in memory and exposed as a ClipboardFile on the resulting ClipboardEvent. Suitable for small pastes; for larger ones use addPasteListener(Component, UploadHandler, SerializableConsumer) with a streaming handler.

      The listener fires once per paste, after every pasted file has been uploaded (or has failed). Failures are reported via addPasteFailedListener(com.vaadin.flow.component.Component, com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.clipboard.ClipboardPasteFailedEvent>); failed files do not appear in ClipboardEvent.getFiles().

      Parameters:
      target - the component to attach the paste handler to, not null
      listener - invoked on the UI thread when the user pastes into the target, not null
      Returns:
      a registration for removing the listener
      Throws:
      NullPointerException - if target or listener is null

    • addPasteListener

      public static Registration addPasteListener(Component target, UploadHandler uploadHandler, SerializableConsumer<ClipboardEvent> listener)
      Adds a paste listener to target with a custom UploadHandler. The handler receives every pasted file's bytes directly — use this to stream large pastes to disk, enforce size limits, or wire TransferProgressListener for fine-grained progress reporting.

      Because the handler owns the file content, the ClipboardEvent delivered to listener carries text and HTML only — ClipboardEvent.getFiles() is always empty. The listener still fires once per paste, after the handler has finished processing every file (successful or failed).

      Parameters:
      target - the component to attach the paste handler to, not null
      uploadHandler - the upload handler that consumes pasted file bytes, not null
      listener - invoked on the UI thread when the user pastes into the target, not null
      Returns:
      a registration for removing the listener
      Throws:
      NullPointerException - if any argument is null

    • addPasteStartListener

      public static Registration addPasteStartListener(Component target, SerializableConsumer<ClipboardPasteStartEvent> listener)
      Adds a listener that fires the moment the browser dispatches a paste event on target, before any pasted file has been uploaded. The event carries text, HTML, and metadata for each pasted file (name, MIME type, size) but no bytes.

      Use this hook to show a progress indicator at the start of a paste — pair it with addPasteListener(com.vaadin.flow.component.Component, com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.clipboard.ClipboardEvent>) (fires after uploads complete) and addPasteFailedListener(com.vaadin.flow.component.Component, com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.clipboard.ClipboardPasteFailedEvent>) (fires per failed file) to dismiss the indicator on success or failure.

      Parameters:
      target - the component to attach the listener to, not null
      listener - invoked on the UI thread when a paste begins, not null
      Returns:
      a registration for removing the listener
      Throws:
      NullPointerException - if target or listener is null

    • addPasteFailedListener

      public static Registration addPasteFailedListener(Component target, SerializableConsumer<ClipboardPasteFailedEvent> listener)
      Adds a listener that fires when uploading a single pasted file fails on the client. The remaining files in the same paste continue uploading; one event is fired per failed file.
      Parameters:
      target - the component to attach the listener to, not null
      listener - invoked on the UI thread for each failed file, not null
      Returns:
      a registration for removing the listener
      Throws:
      NullPointerException - if target or listener is null

    • addCopyListener

      public static Registration addCopyListener(Component target, SerializableConsumer<ClipboardEvent> listener)
      Adds a copy listener to target. The browser's native copy event on the target is forwarded to the server with the text and HTML being copied. Useful for analytics or for triggering side effects (e.g. incrementing a "copies" counter).
      Parameters:
      target - the component to attach the copy handler to, not null
      listener - invoked on the UI thread when the user copies from the target, not null
      Returns:
      a registration for removing the listener
      Throws:
      NullPointerException - if target or listener is null

    • addCutListener

      public static Registration addCutListener(Component target, SerializableConsumer<ClipboardEvent> listener)
      Adds a cut listener to target. The browser's native cut event on the target is forwarded to the server with the text and HTML being cut.
      Parameters:
      target - the component to attach the cut handler to, not null
      listener - invoked on the UI thread when the user cuts from the target, not null
      Returns:
      a registration for removing the listener
      Throws:
      NullPointerException - if target or listener is null

    • availabilityHintSignal

      public static Signal<ClipboardAvailability> availabilityHintSignal()
      Returns a read-only signal hinting at whether the Clipboard API is usable in the current UI's page context.

      Subscribe with Signal.effect(owner, ...) to react to the availability (e.g. to hide a copy button on insecure-context pages). For a snapshot read, call availabilityHintSignal().peek().

      The signal starts as UNKNOWN and transitions to the value reported during the initial client bootstrap. The value is best-effort and intended for pre-rendering decisions; for authoritative results, attempt the operation and inspect the success or error callback.

      Returns:
      the availability hint signal
      Throws:
      IllegalStateException - if there is no current UI

    • availabilityHintSignal

      public static Signal<ClipboardAvailability> availabilityHintSignal(UI ui)
      Returns a read-only signal hinting at whether the Clipboard API is usable in the given UI's page context. Same semantics as availabilityHintSignal(); use this overload from background threads or anywhere UI.getCurrent() is unreliable.
      Parameters:
      ui - the UI to read the hint from, never null
      Returns:
      the availability hint signal
      Throws:
      NullPointerException - if ui is null