Clipboard API

[Artur-]

PRD: Clipboard

Tier: Free
License: Apache 2.0

Description

A cross-browser clipboard API for Vaadin that lets applications copy text and images to the clipboard, receive pasted content (text, HTML, files), and detect clipboard availability — without hand-written JavaScript.

Motivation

Background

Web applications routinely need to interact with the operating-system clipboard. Common examples include "copy to clipboard" buttons next to API keys or share links, and pasting screenshots into upload areas. The browser's Clipboard API makes all of this possible, but it has significant constraints: write operations must happen inside a trusted user-gesture event handler, read operations require explicit permission prompts, and behavior varies across Chrome, Firefox, and Safari.

Vaadin's server-driven architecture adds a further complication. A typical user click travels to the server and back before application code runs, which breaks the browser's "trusted event" requirement for clipboard access. As a result, developers today must write raw JavaScript via UI.getCurrent().getPage().executeJs(...), manage browser quirks themselves, and forgo any framework-level error handling or feedback. Multiple community add-ons have attempted to fill this gap (ClipboardHelper, Clipboard for Flow, JSClipboard, CopyToClipboard, among others), but they tend to break across major Vaadin upgrades and cover only the simplest "copy text" scenario.

Problem

Vaadin developers have no built-in, reliable way to:

1. Copy text to the clipboard on a button click or context-menu action without writing JavaScript. This is the single most requested clipboard capability — needed for API keys, share links, reference numbers, code snippets, and cell values in grids. The workaround (executeJs("navigator.clipboard.writeText(…)")) is fragile, has no error handling, and does not provide user feedback.

2. Receive pasted content. Users expect Ctrl+V to work in relevant areas of the application. There is no framework-level way to listen for paste events and receive the pasted content (text, HTML, or image data) on the server.

3. Degrade gracefully when clipboard access is unavailable (HTTP pages, restrictive iframes, denied permissions, unsupported browsers). Today, failures are silent — the user sees no feedback and the developer has no error callback.

These gaps have been reported repeatedly in GitHub issues (vaadin/flow#17703) and in Vaadin forum threads over several years.

Solution

Provide a general-purpose Clipboard API that lets any Vaadin application write to and read from the clipboard without hand-written JavaScript. The API must handle the browser's trusted-event requirement transparently — for example, by executing the clipboard call directly inside the client-side click handler before the server round-trip, then notifying the server of the result. It must work across Chrome, Firefox, and Safari, and surface errors to the developer when clipboard access fails.

The copy path should provide:

• A way to copy a static string on a user action (button click, context-menu selection).
• A way to copy a dynamically computed value (e.g., reading from a component's current value at copy time).
• Visual feedback (success/failure) that the developer can customize or disable.
• A way to copy image data.

The paste/read path should provide:

• A listener for paste events that delivers the pasted content (text, HTML, image data) to the server.
• Automatic handling of pasted files (images) by converting them to upload-compatible objects.

The API should also provide:

• A way to detect whether clipboard read/write is available in the current environment, so the application can hide or disable clipboard controls proactively.

Notes

• The central tracking issue is vaadin/flow#17703, with a draft PR at vaadin/flow#23615.
• Browser compatibility is a key design constraint. navigator.clipboard.readText() does not work reliably in Firefox (no permission prompt, silently denied) and has restrictions in Safari. The implementation must use strategies that work within each browser's security model — for example, using document.execCommand('copy') as a fallback, or executing clipboard writes synchronously inside the client-side event handler before the server round-trip.
• The Clipboard API is only available in secure contexts (HTTPS). The feature must detect this and degrade gracefully on HTTP pages.

Requirements

• Copy a static text string to the clipboard on a user action (button click, context-menu item)
• Copy a dynamically computed value to the clipboard (e.g., read from a component's current state at copy time)
• Copy image data to the clipboard
• Provide a paste event listener that delivers pasted text content to the server
• Provide a paste event listener that delivers pasted image/file data to the server
• Provide success and failure callbacks for copy operations
  - [ ] Provide a way to detect whether clipboard access is available in the current environment
• Work across all Vaadin-supported browsers
• Degrade gracefully when clipboard access is unavailable (HTTP, restrictive iframes, denied permissions) — no silent failures
• Documentation
• Feature flag

Nice-to-haves

• A dedicated CopyButton web component (similar to Shoelace's sl-copy-button) with built-in icon, tooltip, and success feedback — ready to drop into any layout
• Configurable visual feedback for copy operations (custom tooltip text, icon change duration, animation)

Browserless testing

Each requirement must be testable without a real browser (no Selenium, no Playwright). The implementation must provide the following testing affordances:

• A test helper that simulates the result of a clipboard write operation (success or failure), so server-side success/failure callbacks can be verified in a unit test without an actual browser clipboard.
• A test helper that simulates an incoming paste event with configurable content (plain text, HTML, image bytes), so server-side paste listeners can be exercised.
• A way to query whether the "clipboard available" detection would report available or unavailable, and to override it in tests.

Risks, limitations and breaking changes

Risks

• Browser-compatibility surface area. Clipboard behavior differs significantly across browsers and changes with browser updates. The implementation will need ongoing maintenance to track browser changes, particularly in Firefox and Safari.
• Security review required. Clipboard access is a sensitive browser capability. Reading clipboard content and transmitting it to the server must be done carefully to avoid leaking data the user did not intend to share. Paste listeners should only activate in specific, developer-designated contexts.

Limitations

• Clipboard read (paste) may require a permission prompt in some browsers. The framework cannot suppress or bypass this prompt. Applications that rely on paste functionality must accept that some users will deny the permission.
• Firefox limitations. navigator.clipboard.readText() does not work in Firefox outside of browser extensions as of 2026. Paste-event-based reading (intercepting the paste DOM event) works everywhere and should be the primary mechanism for reading clipboard content.
• HTTPS required. The Clipboard API is only available in secure contexts. Applications served over plain HTTP will not be able to use this feature. The framework should detect this and provide a clear signal to the developer.

Breaking changes

None expected. This is a new API.

Out of scope

• Component-specific clipboard integrations (Grid copy/paste, Upload image paste, MultiSelectComboBox bulk paste, Rich Text Editor paste cleanup).
• Inter-application rich object transfer (e.g., copying a complex domain object from one Vaadin app and pasting it into another with full fidelity). This is a niche scenario better handled at the application level.
• Remote clipboard synchronization for remote desktop or remote shell scenarios.
• Drag-and-drop. While conceptually related to clipboard (both are data-transfer mechanisms), drag-and-drop is a separate feature with its own interaction model and should be handled independently.
• Server-initiated clipboard writes (writing to clipboard without a user gesture). Browsers block this for security reasons and it should not be worked around.

Materials

• vaadin/flow#17703 — Clipboard API — central tracking issue
• vaadin/flow#23615 — Draft PR for Clipboard API

Metrics

Pre-implementation checklist

• Product Manager sign-off
• Engineering Manager sign-off

Pre-release checklist

• Documented (link to documentation provided in sub-issue or comment)
• UX/DX tests conducted and blockers addressed
• Approved for release by Product Manager

Security review

• Not applicable
• Peer reviewed
• Security audit conducted (link to internal report)

[stefanuebe]

https://vaadin.com/directory/component/clipboard-for-flow

Maybe something can be reused from this addon and spare some impl time

[Artur-]

Let's drop "A way to detect whether clipboard read/write is available in the current environment, so the application can hide or disable clipboard controls proactively." until somebody indicates a real need for this. There should be error callbacks so you can deal with this reactively