HomeGuidesReferenceLearn

Reference version

ArchiveExpo SnackDiscord and ForumsNewsletter

Expo Clipboard iconExpo Clipboard

GitHub

npm

A universal library that allows getting and setting Clipboard content.

Android
iOS
Web

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

Installation

Terminal
- npx expo install expo-clipboard

If you are installing this in an existing React Native app, start by installing expo in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.

Usage

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

export default function App() {
  const [copiedText, setCopiedText] = 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.

Component

ClipboardPasteButton

Type: React.Element<ClipboardPasteButtonProps>

This component displays the UIPasteControl button on your screen. This allows pasting from the clipboard without requesting permission from the user.

You should only attempt to render this if Clipboard.isPasteButtonAvailable is true. This component will render nothing if it is not available, and you will get a warning in development mode (__DEV__ === true).

The properties of this component extend from View; however, you should not attempt to set backgroundColor, color or borderRadius with the style property. Apple restricts customisation of this view. Instead, you should use the backgroundColor and foregroundColor properties to set the colors of the button, the cornerStyle property to change the border radius, and the displayMode property to change the appearance of the icon and label. The word "Paste" is not editable and neither is the icon.

Make sure to attach height and width via the style props as without these styles, the button will not appear on the screen.

See: Apple Documentation for more details.

Android
iOS
Web

acceptedContentTypes

Optional • Type: AcceptedContentType[] • Default: ['plain-text', 'image']

An array of the content types that will cause the button to become active.

Do not include plain-text and html at the same time as this will cause all text to be treated as html.

Android
iOS
Web

backgroundColor

Optional • Type: string | null

The backgroundColor of the button. Leaving this as the default allows the color to adjust to the system theme settings.

Android
iOS
Web

cornerStyle

Optional • Type: CornerStyleType | null • Default: 'capsule'

The cornerStyle of the button.

See: Apple Documentation for more details.

Android
iOS
Web

displayMode

Optional • Type: DisplayModeType | null • Default: 'iconAndLabel'

The displayMode of the button.

See: Apple Documentation for more details.

Android
iOS
Web

foregroundColor

Optional • Type: string | null • Default: 'white'

The foregroundColor of the button.

Android
iOS
Web

imageOptions

Optional • Type: GetImageOptions | null

The options to use when pasting an image from the clipboard.

Android
iOS
Web

onPress

Type: (data: PasteEventPayload) => void

A callback that is called with the result of the paste action. Inspect the type property to determine the type of the pasted data.

Can be one of text or image.

Example

  onPress={(data) => {
    if (data.type === 'image') {
      setImageData(data);
   } else {
      setTextData(data);
    }
  }}
Android
iOS
Web

style

Optional • Type: StyleProp<Omit<ViewStyle, 'backgroundColor' | 'borderRadius' | 'color'>>

The custom style to apply to the button. Should not include backgroundColor, borderRadius or color properties.

Inherited Props

Constants

Android
iOS
Web

isPasteButtonAvailable

Type: boolean


Property that determines if the ClipboardPasteButton is available.

This requires the users device to be using at least iOS 16.

true if the component is available, and false otherwise.

Methods

Android
iOS
Web

getImageAsync(options)

ParameterTypeDescription
optionsGetImageOptions

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."

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.

Example

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

getStringAsync(options)

ParameterTypeDescription
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.

iOS

getUrlAsync()

Gets the URL from the user's clipboard.

Returns:

Promise<string | null>

A promise that fulfills to the URL in the clipboard.

Android
iOS
Web

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.

Android
iOS
Web

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.

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.

Android
iOS
Web

setImageAsync(base64Image)

ParameterTypeDescription
base64Imagestring

Image encoded as a base64 string, without MIME type.


Sets an image in the user's clipboard.

Returns:

Promise<void>

Example

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

Deprecated Use setStringAsync() instead.

Android
iOS
Web

setString(text)

ParameterType
textstring

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.

Android
iOS
Web

setStringAsync(text, options)

ParameterTypeDescription
textstring

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.

iOS

setUrlAsync(url)

ParameterTypeDescription
urlstring

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

Android
iOS
Web

addClipboardListener(listener)

ParameterTypeDescription
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.

Returns:

EventSubscription

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');
  }
});
Android
iOS
Web

removeClipboardListener(subscription)

ParameterTypeDescription
subscriptionEventSubscription

The subscription to remove (created by addClipboardListener).


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

Returns:

void

Example

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

Types

Android
iOS
Web

AcceptedContentType

Literal Type: string

Acceptable values are: 'plain-text' | 'image' | 'url' | 'html'

Android
iOS
Web

ClipboardEvent

NameTypeDescription
contentstring

Deprecated Returns empty string. Use getStringAsync() instead to retrieve clipboard content.

contentTypesContentType[]

An array of content types that are available on the clipboard.

Android
iOS
Web

ClipboardImage

NameTypeDescription
datastring

A Base64-encoded string of the image data. Its format is dependent on the format option. You can use it directly as the source of an Image element.

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

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.

Android
iOS
Web

CornerStyleType

Literal Type: string

Acceptable values are: 'dynamic' | 'fixed' | 'capsule' | 'large' | 'medium' | 'small'

Android
iOS
Web

DisplayModeType

Literal Type: string

Acceptable values are: 'iconAndLabel' | 'iconOnly' | 'labelOnly'

Android
iOS
Web

GetImageOptions

NameTypeDescription
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
Android
iOS
Web

GetStringOptions

NameTypeDescription
preferredFormat
(optional)		StringFormat

The target format of the clipboard string to be converted to, if possible.

Default:StringFormat.PLAIN_TEXT
Android
iOS
Web

ImagePasteEvent

Type: ClipboardImage extended by:


NameTypeDescription
type'image'-
Android
iOS
Web

PasteEventPayload

Literal Type: multiple types

Acceptable values are: TextPasteEvent | ImagePasteEvent

Android
iOS
Web

SetStringOptions

NameTypeDescription
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
Android
iOS
Web

Subscription

A subscription object that allows to conveniently remove an event listener from the emitter.

NameTypeDescription
remove() => void

Removes an event listener for which the subscription has been created. After calling this function, the listener will no longer receive any events from the emitter.

Android
iOS
Web

TextPasteEvent

NameTypeDescription
textstring-
type'text'-

Enums

Android
iOS
Web

ContentType

Type used to define what type of data is stored in the clipboard.

ContentType Values

HTML

ContentType.HTML ＝ "html"

IMAGE

ContentType.IMAGE ＝ "image"

PLAIN_TEXT

ContentType.PLAIN_TEXT ＝ "plain-text"
Only for: 
iOS

URL

ContentType.URL ＝ "url"
Android
iOS
Web

StringFormat

Type used to determine string format stored in the clipboard.

StringFormat Values

HTML

StringFormat.HTML ＝ "html"

PLAIN_TEXT

StringFormat.PLAIN_TEXT ＝ "plainText"