Skip to main content

Share.open

The open() method allows a user to share a premade message via a social medium they choose. In other words, code specifies the message that will be sent and the user chooses to whom and the social medium through which the message will be sent. This shared message may contain text, one or more files, or both.

Calling this method will return a promise that will fulfill or be rejected as soon as ther user successfully open the share action sheet or cancel/fail. Because of that, you will need to handle the rejection while necessary.

Using a promise implementation:

Share.open(options)  .then((res) => {    console.log(res);  })  .catch((err) => {    err && console.log(err);  });

Or with async/await:

const fun = async () => {  const shareResponse = await Share.open(options);};

*Keep in mind that using a async/await approach you will still need to handle the error response.

Supported Options#

You can customize the call to Share.open passing the following parameters:

NameTypeDescriptionOptionalAndroidiOSWindows
messagestringMessage sent to the share activityโœ…โœ…โœ…โ“
titlestringTitle sent to the share activityโœ…โœ…โœ…โ“
urlstringURL you want to share (only support base64 string in iOS & Android).โœ…โœ…โœ…โ“
urlsArray[string]Array of base64 string you want to share.โœ…โœ…โœ…โ“
typestringFile mime typeโœ…โœ…โœ…โ“
subjectstringSubject sent when sharing to emailโœ…โœ…โœ…โ“
emailstringEmail of addresseeโœ…โœ…โœ…โ“
recipientstringPhone number of SMS recipientโœ…โœ…๐Ÿšซ๐Ÿšซ
excludedActivityTypesArray[string]Activity types that won't show in the Share dialogโœ…โœ…โœ…โ“
failOnCancelboolean(defaults to true) Specifies whether promise should reject if user cancels share dialogโœ…โœ…โœ…โ“
showAppsToViewbooleanonly androidโœ…โœ…๐Ÿšซโ“
filenamestringOnly support base64 string in Androidโœ…โœ…๐Ÿšซโ“
saveToFilesbooleanOpen only Files app (supports only urls (base64 string or path), requires iOS 11 or later)โœ…๐Ÿšซโœ…โ“
filenamesArray[string]Array of filename for base64 urls array in Androidโœ…โœ…๐Ÿšซโ“
activityItemSourcesArray[Object]Array of activity item sources. Each items should conform to ActivityItemSource specification. Example.โœ…๐Ÿšซโœ…โ“
useInternalStoragebooleanStore the temporary file in the internal storage cache (Android only)โœ…โœ…๐Ÿšซ๐Ÿšซ
isNewTaskbooleanOpen intent as a new task. "failOnCancel" will not work.โœ…โœ…๐Ÿšซโ“

Sharing a base64 file format#

When sharing a base64 file, you will need to follow the format below:

url: "data:<data_type>/<file_extension>;base64,<base64_data>"

Note: If your application requires the ability to share base64 files on Android, you need to add

<!-- required for react-native-share base64 sharing --><uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

to your application's AndroidManifest.xml file as per the example project.

Sharing a file directly#

When sharing a local file directly, you can use the following format:

url: "file://<file_path>"

ActivityItemSources (iOS only)#

In order to share different data according to activities or to customize the share sheet, you can provide the data by using activityItemSources .

See here for more information about UIActivityItemSource.

Example ActivityItemSources#

import { Platform } from 'react-native';import Share from 'react-native-share';
const url = 'https://awesome.contents.com/';const title = 'Awesome Contents';const message = 'Please check this out.';const icon = 'data:<data_type>/<file_extension>;base64,<base64_data>';const options = Platform.select({  ios: {    activityItemSources: [      {        // For sharing url with custom title.        placeholderItem: { type: 'url', content: url },        item: {          default: { type: 'url', content: url },        },        subject: {          default: title,        },        linkMetadata: { originalUrl: url, url, title },      },      {        // For sharing text.        placeholderItem: { type: 'text', content: message },        item: {          default: { type: 'text', content: message },          message: null, // Specify no text to share via Messages app.        },        linkMetadata: {          // For showing app icon on share preview.          title: message,        },      },      {        // For using custom icon instead of default text icon at share preview when sharing with message.        placeholderItem: {          type: 'url',          content: icon,        },        item: {          default: {            type: 'text',            content: `${message} ${url}`,          },        },        linkMetadata: {          title: message,          icon: icon,        },      },    ],  },  default: {    title,    subject: title,    message: `${message} ${url}`,  },});
Share.open(options);

ActivityItemSource#

Structure used when the option activityItemSources is being used:

NameTypeDescription
placeholderItemObjectAn object to use as a placeholder for the actual data. This should comform to ActivityItem type.
itemObjectAn object that contains the final data object to be acted on for each activity types. This should be { [ActivityType]: ?ActivityItem } .
subjectObject(optional) An object that contains a string to use as the contents of the subject field for each activity types. This should be { [ActivityType]: string } .
dataTypeIdentifierObject(optional) An object that contains the UTI for the item for each activity types. This should be { [ActivityType]: string } . See here for more information.
thumbnailImageObject(optional) An object that contains the URL to the image to use as a preview for the item for each activity types. This should be { [ActivityType]: string } . The URL should begin with data: and contain the data as base 64 encoded string.
linkMetadataObject(optional) An object that contains the metadata about a URL, including its title, icon, images, and video. See LinkMetadata.

ActivityType#

  • addToReadingList
  • airDrop
  • assignToContact
  • copyToPasteBoard
  • mail
  • message
  • openInIBooks (iOS 9+)
  • postToFacebook
  • postToFlickr
  • postToTencentWeibo
  • postToTwitter
  • postToVimeo
  • postToWeibo
  • print
  • saveToCameraRoll
  • markupAsPDF (iOS 11+)

Also you can use default in order to specify default behavior.

ActivityItem#

NameTypeDescription
typetext | urlType of the content.
contentstringText or URL to share. You can specify image with URL that begins with data and contains the data as base 64 encoded string.

LinkMetadata#

NameTypeDescription
originalUrlstring(optional) The original URL of the metadata request.
urlstring(optional) The URL that returns the metadata, taking server-side redirects into account.
titlestring(optional) A representative title for the URL.
iconstring(optional) A URL of the file corresponding to a representative icon for the URL.
imagestring(optional) A URL of the file corresponding to a representative image for the URL.
remoteVideoUrlstring(optional) A remote URL corresponding to a representative video for the URL.
videostring(optional) A URL of the file corresponding to a representative video for the URL.

LSApplicationQueriesSchemes (iOS only)#

If you want to share Whatsapp, Mailto or some applications on iOS, you should write LSApplicationQueriesSchemes in info.plist:

  <key>LSApplicationQueriesSchemes</key>  <array>    <string>whatsapp</string>    <string>mailto</string>  </array>

Also, to save photos your gallery you will need setting the following permission on your Info.plist:

  <key>NSPhotoLibraryAddUsageDescription</key>  <string>$(PRODUCT_NAME) wants to save photos</string>