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.
-
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.
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',
},
});
import * as Clipboard from 'expo-clipboard';
On Web, this module uses theAsyncClipboard
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.
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.
acceptedContentTypes
AcceptedContentType[]
• Default: ['plain-text', 'image']
An array of the content types that will cause the button to become active.
Do not include
plain-text
andhtml
at the same time as this will cause all text to be treated ashtml
.
backgroundColor
string | null
The backgroundColor of the button. Leaving this as the default allows the color to adjust to the system theme settings.
cornerStyle
CornerStyleType | null
• Default: 'capsule'
The cornerStyle of the button.
See: Apple Documentation for more details.
displayMode
DisplayModeType | null
• Default: 'iconAndLabel'
The displayMode of the button.
See: Apple Documentation for more details.
imageOptions
GetImageOptions | null
The options to use when pasting an image from the clipboard.
onPress
(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);
}
}}
style
The custom style to apply to the button. Should not include backgroundColor
, borderRadius
or color
properties.
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.
getImageAsync(options)
Parameter | Type | Description |
---|---|---|
options | GetImageOptions | A |
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."
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 }} />
getStringAsync(options)
Parameter | 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."
Promise<string>
A promise that resolves to the content of the clipboard.
getUrlAsync()
Gets the URL from the user's clipboard.
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".
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".
Promise<boolean>
A promise that fulfills to true
if clipboard has text content, resolves to false
otherwise.
hasUrlAsync()
Returns whether the clipboard has a URL content.
Promise<boolean>
A promise that fulfills to true
if clipboard has URL content, resolves to false
otherwise.
setImageAsync(base64Image)
Parameter | Type | Description |
---|---|---|
base64Image | string | Image encoded as a base64 string, without MIME type. |
Sets an image in the user's clipboard.
Promise<void>
Example
const result = await ImagePicker.launchImageLibraryAsync({
mediaTypes: ImagePicker.MediaTypeOptions.Images,
base64: true,
});
await Clipboard.setImageAsync(result.base64);
Deprecated Use
setStringAsync()
instead.
setString(text)
Parameter | Type |
---|---|
text | string |
Sets the content of the user's clipboard.
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)
Parameter | 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.
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
.
setUrlAsync(url)
Parameter | 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.
Promise<void>
addClipboardListener(listener)
Parameter | 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');
}
});
removeClipboardListener(subscription)
Parameter | 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.
void
Example
const subscription = addClipboardListener(() => {
alert('Copy pasta!');
});
removeClipboardListener(subscription);
AcceptedContentType
Literal Type: string
Acceptable values are: 'plain-text'
| 'image'
| 'url'
| 'html'
ClipboardEvent
Name | Type | Description |
---|---|---|
content | string |
|
contentTypes | ContentType[] | An array of content types that are available on the clipboard. |
ClipboardImage
Name | Type | Description |
---|---|---|
data | string | A Base64-encoded string of the image data. Its format is dependent on the
Example
|
size | {
height: number,
width: number
} | Dimensions ( |
CornerStyleType
Literal Type: string
Acceptable values are: 'dynamic'
| 'fixed'
| 'capsule'
| 'large'
| 'medium'
| 'small'
GetImageOptions
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 Default: 1 |
GetStringOptions
Name | Type | Description |
---|---|---|
preferredFormat (optional) | StringFormat | The target format of the clipboard string to be converted to, if possible. Default: StringFormat.PLAIN_TEXT |
PasteEventPayload
Literal Type: multiple types
Acceptable values are: TextPasteEvent
| ImagePasteEvent
SetStringOptions
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 |
Subscription
Name | Type | Description |
---|---|---|
remove | () => void | A method to unsubscribe the listener. |
TextPasteEvent
Name | Type | Description |
---|---|---|
text | string | - |
type | 'text' | - |
HTML
ContentType.HTML = "html"
IMAGE
ContentType.IMAGE = "image"
PLAIN_TEXT
ContentType.PLAIN_TEXT = "plain-text"
HTML
StringFormat.HTML = "html"
PLAIN_TEXT
StringFormat.PLAIN_TEXT = "plainText"