Skip to content

Clipboard

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 Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Layer that directly interfaces with the browser Clipboard API.

Signature

declare const layer: Layer.Layer<Clipboard>;

Services

Clipboard

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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>;
}