Share

Share text, links, and files through the system share sheet, and learn whether people finished

One.Share.share opens the system share sheet with any mix of text, links, and files, and resolves once people finish or cancel. On iOS it is UIActivityViewController; on Android it is the system chooser with a send intent; on web it is navigator.share.

It is the share API to use for files and when you need to know the outcome. For a quick message and link, One.openShare on Opening URLs and Settings is simpler; for a share button with a fixed item, One.iOS.ShareLink draws the system control.

Usage

import { Button } from 'react-native'
import { One } from 'one'

function ShareInvite({ code }: { code: string }) {
  return (
    <Button
      title="Invite a friend"
      onPress={async () => {
        const result = await One.Share.share([
          { type: 'text', value: `Join me with code ${code}` },
          { type: 'url', value: `https://example.com/invite/${code}` },
        ])
        if (result.completed) console.log('Shared via', result.activityType ?? 'a system action')
      }}
    />
  )
}

How it works

Items. Each item is text, url, or file. Text must not be blank. A URL must be absolute and not a file:// URL. A file must be a file:// URI to a file that exists. Every item is checked before the sheet opens, and the first bad one rejects the call.

iOS. Each item becomes its own activity item, so a link arrives as a real URL and a file as an attachment. The sheet presents over the top-most screen, centered on iPad. The promise resolves when the sheet closes: completed is true when people finished an action, and activityType names it, such as com.apple.UIKit.activity.Mail or another app’s share extension.

Android. Text items and URLs are joined with line breaks into one text. A single file goes out alone with a type guessed from its extension; several files, or files with text, go out together as a multiple send. Files are handed over through One’s file provider with read permission for the chosen app. completed is true once a target app is chosen, and activityType is that app’s component name. Dismissing the chooser resolves { completed: false }.

One sheet at a time. A second call while a sheet is open rejects, with E_SHARE_BUSY on iOS and Android. The sheet needs the app in the foreground; otherwise the call rejects with E_SHARE_PRESENTATION.

Web. Text items join with line breaks, the URL goes in its own field, and files are fetched and passed as File objects. Cancelling resolves { completed: false }. Browsers allow only one URL per share and never say which app was picked.

API reference

iOS and Android reject with these codes. On web the same failures reject with a message and no code.

Platform differences

Limits and gotchas

• Android shares files from the cache only. The file provider serves the app’s cache folder, so a file elsewhere, such as in documents, rejects with E_SHARE_FILE. Copy it into Paths.cache first, as the example below does.
• Completed is a hint. On Android it means an app was chosen, not that the message was sent; that app may still be cancelled. Don’t grant rewards or count shares on it alone.
• Call it from a tap. The sheet needs the app active and no screen transition running. Calling during a navigation animation rejects with E_SHARE_PRESENTATION.
• Web is stricter. Browsers need a user gesture and support for the share API; without it the call rejects. More than one URL, a file:// file, or files the browser refuses all reject before the sheet opens.

Examples

import { One } from 'one'

const { File, Paths } = One.FileSystem

async function shareReport(csv: string) {
  const file = new File(Paths.cache, 'report.csv')
  await file.write(csv)
  return One.Share.share([{ type: 'file', value: file.uri }])
}

Writing into the cache folder makes the file shareable on Android as well as iOS. The .csv extension gives Android the right type, so spreadsheet apps show up in the chooser.

import { One } from 'one'

async function sharePhoto(caption: string) {
  const picked = await One.ImagePicker.launchLibrary()
  if (picked.canceled) return null
  return One.Share.share([
    { type: 'file', value: picked.assets[0].uri },
    { type: 'text', value: caption },
  ])
}

Picked assets are already copies in the app cache, so they share directly on both platforms. Apps that accept both take the photo and the caption together.