clipawl 0.2.1

Clipboard API for Rust: Web (wasm), Android, and Linux (Wayland + X11) with a portable async API
Documentation

clipawl

A minimal, effective clipboard crate for Rust with a portable async API.

Supported platforms:

  • Web (wasm32) via navigator.clipboard
  • Android via JNI + ClipboardManager
  • Linux via Wayland (wl-clipboard-rs) + X11 (clipboard_x11) with runtime detection

Features

  • Async-first API — works naturally with web's Promise-based clipboard
  • Platform detection — automatically picks Wayland or X11 on Linux
  • Documented pitfalls — explicit about Linux selection ownership, web permissions, etc.

Quick Start

use clipawl::{Clipboard, Error};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let mut clipboard = Clipboard::new()?;

    // Write
    clipboard.set_text("Hello from clipawl!").await?;

    // Read
    let text = clipboard.get_text().await?;
    println!("Clipboard: {}", text);

    Ok(())
}

Platform Notes

Web (wasm32)

  • Requires secure context (HTTPS or localhost)
  • Requires user activation (click/keypress) for most browsers
  • Not available in Web Workers

Android

  • Uses ClipboardManager via JNI
  • getPrimaryClip() may return null if app lacks input focus or isn't the default IME
  • Requires ndk-context to be initialized (handled by most Android frameworks)

Linux

Selection ownership model: On X11 and Wayland, the app that sets the clipboard often must continue serving the data. If your app exits immediately after set_text(), the clipboard may appear empty to other apps.

Workarounds:

  • Keep the Clipboard instance alive longer
  • Use a clipboard manager (e.g., clipman, wl-clipboard)
  • Future: set_text_persistent() (planned)

Wayland: Requires compositor support for wlr-data-control or ext-data-control protocols. If unavailable, clipawl falls back to X11 (XWayland).

Options

use clipawl::{Clipboard, ClipboardOptions, LinuxBackend, LinuxSelection};

let opts = ClipboardOptions {
    linux: LinuxOptions {
        selection: LinuxSelection::Primary,  // Use PRIMARY selection (middle-click paste)
        backend: LinuxBackend::X11,          // Force X11 backend
    },
};

let clipboard = Clipboard::new_with_options(opts)?;

Cargo Features

  • linux-wayland (default) — Enable Wayland backend
  • linux-x11 (default) — Enable X11 backend

Disable defaults to reduce dependencies:

clipawl = { version = "0.1", default-features = false, features = ["linux-x11"] }

Roadmap

  • v0.1: Text read/write on Web, Android, Linux
  • v0.2: Linux reliability knobs (wait-for-paste, better error messages)
  • v0.3: Persistent copy for CLI workflows
  • v0.4: Additional formats (HTML, image)

License

Licensed under either of:

at your option.