Native sharing
Open the device's native share sheet to share text, images, video, files, or an Instagram Story.
Open the share sheet
Hand content to the device's native share sheet so the user can send it to another app like Messages, Mail, or Instagram. There is no result event — the call resolves once the sheet is requested, not when the user completes or cancels the share.
When not running in the app, the call doesn't run — triggered is false (pending in a browser tab, skipped with no window).
const bdk = createBdkNative();
// Each method dispatches and forgets — await confirms the sheet was requested.
await bdk.share.text({ text_content: "Check out this app!" });
Share text
Share a string of text. The only field is text_content — to share a link, include the URL in the text. Use it for "Share this link" and "Tell a friend" flows.
const bdk = createBdkNative();
await bdk.share.text({ text_content: "Check out this app! https://example.com" });
Share an image
Share a hosted image by URL. Pass a bare string, not an object.
A protocol-relative URL beginning with // is upgraded to https://.
const bdk = createBdkNative();
await bdk.share.image("https://example.com/photos/sunset.jpg");
Share a video
Share a video by URL. Pass a bare string.
const bdk = createBdkNative();
await bdk.share.video("https://example.com/clips/demo.mp4");
Share a file
Share any file by URL — a PDF, a document, a download. Pass a bare string.
const bdk = createBdkNative();
await bdk.share.file("https://example.com/docs/invoice.pdf");
Share to an Instagram Story
Open content directly in the Instagram Stories composer for a one-tap "Share to your Story" button.
const bdk = createBdkNative();
await bdk.share.instagramStory({
app_id: "your-instagram-app-id",
background_image_url: "https://example.com/story-bg.jpg",
sticker_url: "https://example.com/sticker.png"
});
Check the result
Each method resolves a NativeCommandResult. Inspect triggered to confirm the share sheet opened — there is no event reporting whether the user finished the share.
const bdk = createBdkNative();
const result = await bdk.share.image("https://example.com/photo.jpg");
console.log(result.command); // "shareImage"
console.log(result.triggered); // true if it reached the app
if (!result.triggered) {
console.log("Share unavailable:", result.reason);
}
Share files and links
Open the share sheet with a mixed list of text, links, and files — up to 10 items. On iOS outcome is completed; on Android it is presented. To receive content other apps share into yours, see Receive shared content.
| Property | Type | Description |
|---|---|---|
items | BdkShareItem[] | Mixed { type: "text", text }, { type: "url", url }, and { type: "file", url, filename? } items (image / video / audio are the same file family). Combined with urls, at most 10. See BdkShareItem. |
urls | string[] | File URLs appended after items. Combined with items, at most 10. Pass at least one of items or urls. |
title | string | Android chooser title. Ignored on iOS. |
This feature can be switched off in a given app build. Check await bdk.capabilities.has("share.files") before showing the UI — see Detect features. When it's off, the call resolves ok: false with code: "common/feature_disabled".
Remote file URLs are fetched with the webview's cookie session — files behind a login the webview holds work; files needing an Authorization header don't.
import { createBdkNative } from "@bdk/native/browser";
const bdk = createBdkNative();
const result = await bdk.share.send({
items: [
{ type: "text", text: "Quarterly report attached" },
{ type: "url", url: "https://app.example.com/reports/123" },
{ type: "file", url: "https://app.example.com/api/report.pdf", filename: "Q3-report.pdf" }
],
title: "Share report"
});
if (!result.ok) {
// "share/fetch_failed" | "share/too_large" | "common/feature_disabled"
// In a plain browser the result has ok: false with a feature-disabled code.
console.log(result.code ?? "Share unavailable");
return;
}
console.log(result.outcome); // "completed" on iOS, "presented" on Android
console.log(result.items.requested, result.items.shared);
Share a list of files
Share one or more file URLs. share.files is sugar for share.send with only urls.
const result = await bdk.share.files(
["https://app.example.com/api/report.pdf"],
{ title: "Share report" }
);
if (!result.ok) {
console.log(result.code, result.message);
return;
}
console.log(result.outcome, result.items.shared);