use-share - Vize

Share text, links, and files through the platform share sheet.


Package	`@vizejs/composable/use-share`
Own the source	`vize lib pull composable:use-share`
Runtime exports	`useShare`
Gzip budget	1280 B

Usage

import { useShare } from "@vizejs/composable/use-share";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useShare`	system	experimental	deterministic-fallback	caller-managed	none	web, desktop	`window`	—

API

`useShare`

Share text, links, and files through the platform share sheet. Reactive defaults are merged with per-call overrides. Outcomes are reported as a discriminated ShareResult, so a user dismissing the sheet ("cancelled") is distinguishable from missing support or invalid data without try/catch. Server rendering: no capability is resolved, supported is false, and nothing is shared. No resources are retained, so nothing needs cleanup.

function useShare( defaults: MaybeRefOrGetter<ShareDataLike> = {}, options: UseShareOptions = {}, ): ShareControls

const { share, supported } = useShare(() => ({ title: document.title, url: location.href }));
const onClick = () => share();

Types

`ShareDataLike`

Data shared through the Web Share API.

Member	Type	Description
`title`?	`string`	Title of the shared content.
`text`?	`string`	Body text of the shared content.
`url`?	`string`	URL of the shared content.
`files`?	`File[]`	Files to share (Level 2 of the Web Share API).

`ShareHost`

Minimal Web Share capability (navigator).

Member	Type	Description
`share`	`(data: ShareDataLike) => Promise<void>`	Open the platform share sheet.
`canShare`?	`(data?: ShareDataLike) => boolean`	Whether the platform can share `data`. Absent in older engines.

`UseShareOptions`

Options for useShare.

Member	Type	Description
`host`?	`MaybeRefOrGetter<ShareHost \| null \| undefined>`	Web Share capability for alternate runtimes and tests.

`ShareControls`

Reactive state and actions returned by useShare.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the Web Share API is available.
`sharing`	`Readonly<Ref<boolean>>`	Whether a share sheet opened by this composable is currently open.
`canShare`	`(data?: ShareDataLike) => boolean`	Whether the platform can share the given (or default) data.
`share`	`(overrides?: ShareDataLike) => Promise<ShareResult>`	Open the share sheet. Must run inside a user gesture in browsers.