Reference version

SDK 48

Archive Expo Snack Discord and Forums Newsletter

Expo Clipboard

GitHub

npm

A universal library that allows getting and setting Clipboard content.

expo-clipboard provides an interface for getting and setting Clipboard content on Android, iOS, and Web.

Platform Compatibility

Android Device	Android Emulator	iOS Device	iOS Simulator	Web

Installation

Terminal

- npx expo install expo-clipboard

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Usage

Clipboard

import * as React from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';
import * as Clipboard from 'expo-clipboard';

export default function App() {
  const [copiedText, setCopiedText] = React.useState('');

  const copyToClipboard = async () => {
    await Clipboard.setStringAsync('hello world');
  };

  const fetchCopiedText = async () => {
    const text = await Clipboard.getStringAsync();
    setCopiedText(text);
  };

  return (
    <View style={styles.container}>
      <Button title="Click here to copy to Clipboard" onPress={copyToClipboard} />
      <Button title="View copied text" onPress={fetchCopiedText} />
      <Text style={styles.copiedText}>{copiedText}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  copiedText: {
    marginTop: 10,
    color: 'red',
  },
});

API

import * as Clipboard from 'expo-clipboard';

On Web, this module uses the AsyncClipboard API, which might behave differently between browsers or not be fully supported. Especially on WebKit, there's an issue which makes this API unusable in asynchronous code. Click here for more details.

Methods

`getImageAsync(options)`

Name	Type	Description
options	`GetImageOptions`	A `GetImageOptions` object to specify the desired format of the image.

Gets the image from the user's clipboard and returns it in the specified format. Please note that calling this method on web will prompt the user to grant your app permission to "see text and images copied to the clipboard."

Example

const img = await Clipboard.getImageAsync({ format: 'png' });
// ...
<Image source={{ uri: img?.data }} style={{ width: 200, height: 200 }} />

Returns

Promise<ClipboardImage | null>

If there was an image in the clipboard, the promise resolves to a ClipboardImage object containing the base64 string and metadata of the image. Otherwise, it resolves to null.

`getStringAsync(options)`

Name	Type	Description
options (optional)	`GetStringOptions`	Options for the clipboard content to be retrieved. Default: `{}`

Gets the content of the user's clipboard. Please note that calling this method on web will prompt the user to grant your app permission to "see text and images copied to the clipboard."

Returns

Promise<string>

A promise that resolves to the content of the clipboard.

Only for:

iOS

`getUrlAsync()`

Gets the URL from the user's clipboard.

Returns

Promise<string | null>

A promise that fulfills to the URL in the clipboard.

`hasImageAsync()`

Returns whether the clipboard has an image content.

On web, this requires the user to grant your app permission to "see text and images copied to the clipboard".

Returns

Promise<boolean>

A promise that fulfills to true if clipboard has image content, resolves to false otherwise.

`hasStringAsync()`

Returns whether the clipboard has text content. Returns true for both plain text and rich text (e.g. HTML).

On web, this requires the user to grant your app permission to "see text and images copied to the clipboard".

Returns

Promise<boolean>

A promise that fulfills to true if clipboard has text content, resolves to false otherwise.

Only for:

iOS

`hasUrlAsync()`

Returns whether the clipboard has a URL content.

Returns

Promise<boolean>

A promise that fulfills to true if clipboard has URL content, resolves to false otherwise.

`setImageAsync(base64Image)`

Name	Type	Description
base64Image	`string`	Image encoded as a base64 string, without MIME type.

Sets an image in the user's clipboard.

Example

const result = await ImagePicker.launchImageLibraryAsync({
  mediaTypes: ImagePicker.MediaTypeOptions.Images,
  base64: true,
});
await Clipboard.setImageAsync(result.base64);

Returns

Promise<void>

Deprecated. Use setStringAsync() instead.

`setString(text)`

Name	Type	Description
text	`string`	-

Sets the content of the user's clipboard.

Returns

void

On web, this returns a boolean value indicating whether or not the string was saved to the user's clipboard. On iOS and Android, nothing is returned.

`setStringAsync(text, options)`

Name	Type	Description
text	`string`	The string to save to the clipboard.
options (optional)	`SetStringOptions`	Options for the clipboard content to be set. Default: `{}`

Sets the content of the user's clipboard.

Returns

Promise<boolean>

On web, this returns a promise that fulfills to a boolean value indicating whether or not the string was saved to the user's clipboard. On iOS and Android, the promise always resolves to true.

Only for:

iOS

`setUrlAsync(url)`

Name	Type	Description
url	`string`	The URL to save to the clipboard.

Sets a URL in the user's clipboard.

This function behaves the same as setStringAsync(), except that it sets the clipboard content type to be a URL. It lets your app or other apps know that the clipboard contains a URL and behave accordingly.

Returns

Promise<void>

Event Subscriptions

`addClipboardListener(listener)`

Name	Type	Description
listener	`(event: ClipboardEvent) => void`	Callback to execute when listener is triggered. The callback is provided a single argument that is an object containing information about clipboard contents.

Adds a listener that will fire whenever the content of the user's clipboard changes. This method is a no-op on Web.

Example

Clipboard.addClipboardListener(({ contentTypes }: ClipboardEvent) => {
  if (contentTypes.includes(Clipboard.ContentType.PLAIN_TEXT)) {
    Clipboard.getStringAsync().then(content => {
      alert('Copy pasta! Here\'s the string that was copied: ' + content)
    });
  } else if (contentTypes.includes(Clipboard.ContentType.IMAGE)) {
    alert('Yay! Clipboard contains an image');
  }
});

Returns

Subscription

`removeClipboardListener(subscription)`

Name	Type	Description
subscription	`Subscription`	The subscription to remove (created by addClipboardListener).

Removes the listener added by addClipboardListener. This method is a no-op on Web.

Example

const subscription = addClipboardListener(() => {
  alert('Copy pasta!');
});
removeClipboardListener(subscription);

Returns

void

Interfaces

`ClipboardImage`

ClipboardImage Properties

Name Type Description

Name	Type	Description
data	`string`	A Base64-encoded string of the image data. Its format is dependent on the `format` option. NOTE: The string is already prepended with `data:image/png;base64,` or `data:image/jpeg;base64,` prefix. You can use it directly as the source of an `Image` element. Example `<Image source={{ uri: clipboardImage.data }} style={{ width: 200, height: 200 }} />`
size	`{ height: number, width: number }`	Dimensions (`width` and `height`) of the image pasted from clipboard.

data

string

A Base64-encoded string of the image data. Its format is dependent on the format option.

NOTE: The string is already prepended with data:image/png;base64, or data:image/jpeg;base64, prefix.

You can use it directly as the source of an Image element.

Example

<Image
  source={{ uri: clipboardImage.data }}
  style={{ width: 200, height: 200 }}
/>

size

{
  height: number, 
  width: number
}

Dimensions (width and height) of the image pasted from clipboard.

`GetImageOptions`

GetImageOptions Properties

Name	Type	Description
format	`'png' \| 'jpeg'`	The format of the clipboard image to be converted to.
jpegQuality (optional)	`number`	Specify the quality of the returned image, between `0` and `1`. Defaults to `1` (highest quality). Applicable only when `format` is set to `jpeg`, ignored otherwise. Default: `1`

`GetStringOptions`

GetStringOptions Properties

Name	Type	Description
preferredFormat (optional)	`StringFormat`	The target format of the clipboard string to be converted to, if possible. Default: `StringFormat.PLAIN_TEXT`

`SetStringOptions`

SetStringOptions Properties

Name	Type	Description
inputFormat (optional)	`StringFormat`	The input format of the provided string. Adjusting this option can help other applications interpret copied string properly. Default: `StringFormat.PLAIN_TEXT`

Types

`ClipboardEvent`

Name	Type	Description
content	`string`	Deprecated. Returns empty string. Use `getStringAsync()` instead to retrieve clipboard content.
contentTypes	`ContentType[]`	An array of content types that are available on the clipboard.

`Subscription`

Name	Type	Description
remove	`() => void`	-

iOS

Expo Clipboard

Platform Compatibility

Installation

Usage

API

Methods

`getImageAsync(options)`

`getStringAsync(options)`

`getUrlAsync()`

`hasImageAsync()`

`hasStringAsync()`

`hasUrlAsync()`

`setImageAsync(base64Image)`

`setString(text)`

`setStringAsync(text, options)`

`setUrlAsync(url)`

Event Subscriptions

`addClipboardListener(listener)`

`removeClipboardListener(subscription)`

Interfaces

`ClipboardImage`

`GetImageOptions`

`GetStringOptions`

`SetStringOptions`

Types

`ClipboardEvent`

`Subscription`

Enums

`ContentType`

`HTML`

`IMAGE`

`PLAIN_TEXT`

`URL`

`StringFormat`

`HTML`

`PLAIN_TEXT`