Clipboard unstable

Browser clipboard integration for Effect programs.

This module defines the Clipboard service, the ClipboardError raised by failed browser operations, a make constructor for custom implementations, and a browser-backed layer that uses navigator.clipboard. The service supports reading and writing text, reading and writing ClipboardItem payloads, writing one Blob, and clearing the clipboard.

5 exports Since v4.0.0 Source

Constructors

make

unstable

Since v4.0.0

Builds a Clipboard service from primitive read and write operations, deriving clear and writeBlob helpers.

Signature

declare function make(impl: Omit<Clipboard, "clear" | "writeBlob" | typeof TypeId>): Clipboard

Errors

ClipboardError

unstable

Since v4.0.0

Tagged error raised when a browser clipboard operation fails.

Signature

declare class ClipboardError extends YieldableError<this> & {
  readonly _tag: "ClipboardError";
} & Readonly<{
  readonly cause: unknown;
  readonly message: string;
}> {
  constructor(args: {
    readonly cause: unknown;
    readonly message: string;
  });
  readonly "~@effect/platform-browser/Clipboard/ClipboardError": "~@effect/platform-browser/Clipboard/ClipboardError";
}

Layers

layer

unstable

Since v4.0.0

Layer that directly interfaces with the browser Clipboard API.

Signature

declare const layer: Layer.Layer<Clipboard>

Services

Clipboard

unstable

Since v4.0.0

Service tag for browser clipboard capabilities.

When to use

Use when you need to require or provide clipboard capabilities through Effect's context.

See

make for building a custom clipboard service
layer for providing the browser-backed clipboard service

Signature

declare const Clipboard: Service<Clipboard, Clipboard>

Clipboard

interface unstable

Since v4.0.0

Defines the service interface for reading from, writing to, and clearing the browser clipboard.

When to use

Use when an application needs clipboard operations through an Effect service so browser failures stay in the error channel.

Details

read and write work with ClipboardItem arrays. readString and writeString use text, writeBlob writes one Blob, and clear writes an empty string.

Gotchas

Clipboard access generally requires a secure context and may require user activation, permissions, or a focused document. ClipboardItem and non-text MIME type support varies by browser. Failed browser operations are surfaced as ClipboardError.

Signature

interface Clipboard {
  readonly "~@effect/platform-browser/Clipboard": "~@effect/platform-browser/Clipboard";
  readonly clear: Effect<void, ClipboardError>;
  readonly read: Effect<ClipboardItems, ClipboardError>;
  readonly readString: Effect<string, ClipboardError>;
  readonly write: (items: ClipboardItems) => Effect<void, ClipboardError>;
  readonly writeBlob: (blob: Blob) => Effect<void, ClipboardError>;
  readonly writeString: (text: string) => Effect<void, ClipboardError>;
}