# ShareLink **Maturity:** experimental A user-invokable control that shares content — the SwiftUI ShareLink. ## Import ```tsx import { ShareLink } from "@liquidify/react/share-link" ``` ## Props - `aria-label`: `string | undefined`. Accessible name override — required when {@link children} is icon-only. - `children`: `ReactNode`. Custom label. Omit for the default — the "Share" text preceded by the `share` {@link Icon} glyph, matching SwiftUI's default `ShareLink` label. Omit alongside a {@link leadingIcon} / {@link trailingIcon} for an icon-only trigger (supply an `aria-label` in that case). children role: `label` (token parity — ShareLink's text renders through Button, via Link; no `labelProps` seam, per ADR-0028 rule 3 / charter §2 rule 5). - `className`: `string | undefined`. Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean. - `disabled`: `boolean | undefined`. Disables the control, delegated to {@link Link}. - `item`: `string` (required). The content to share — SwiftUI `ShareLink(item:)`. A value that parses as an absolute URL is shared as the payload's `url`; anything else as its `text`. Required: a ShareLink with nothing to share has no meaning. - `leadingIcon`: `ReactNode`. Leading glyph, forwarded to {@link Link}. Supplying either icon slot suppresses the default `share` glyph so the consumer's icon stands alone. - `message`: `string | undefined`. Optional accompanying message — SwiftUI `ShareLink(message:)`. Maps to the Web Share payload's `text`, shown alongside a shared `url`. - `onClick`: `((event: MouseEvent) => void) | undefined`. Low-level native passthrough; prefer `onPress`. Fires FIRST — call `event.preventDefault()` here to suppress `onPress` **and** the share invocation (charter §1 rules 2–3). - `onError`: `((error: unknown) => void) | undefined`. Called when the native share sheet rejects for a reason other than the user cancelling it (`AbortError`, which is always swallowed silently, as on iOS). Web Share can reject for e.g. a malformed payload or a permissions failure; without a handler the failure is handed to {@link globalThis.reportError} as a documented fallback — surfacing to the global error-reporting path (`window.onerror` / devtools) rather than being silently lost. - `onPress`: `(() => void) | undefined`. Semantic activation — SwiftUI's share action closure, payload-free and fired at most once per interaction (charter §1 rule 1). Fires AFTER the {@link onClick} escape hatch when it did not cancel, and immediately before the Web Share invocation. Disabled emits nothing. - `onShare`: `((item: string) => void) | undefined`. Called with {@link item} after a successful native share, AND as the fallback when the Web Share API is unavailable — the consumer's hook to copy to the clipboard, open a custom menu, or record analytics. Not called when the user cancels the native sheet. A *completion* callback, not activation — unchanged by the `onPress` addition (charter §1). - `ref`: `Ref | undefined`. Forwarded ref to the rendered element — the component's native root (or the merged child element on a component that opts into {@link SlottableProps}). Generic over `E` (charter `docs/api-conventions.md` §4 rule 1, default `HTMLElement`) so a component with a polymorphic root (Link's navigation / action mode union, Text's `as`) can instantiate the concrete element per variant instead of leaving every consumer with a widened `Ref`. A component that does not narrow simply inherits the `HTMLElement` default — source-compatible with every pre-existing non-generic `extends ControlProps`. - `size`: `ButtonSize | undefined`. Control size, delegated to {@link Link} — narrows the inherited {@link SizedControlProps} `size` axis to the three sizes the glass surface ships. - `subject`: `string | undefined`. Optional share title — SwiftUI `ShareLink(subject:)`. Maps to the Web Share payload's `title` (e.g. the pre-filled subject line of an email share). - `tint`: `LiquidTintValue | undefined`. System-accent of the control — drawn from the RESTRICTED {@link LIQUID_COLORS} palette (the thirteen Apple system colours). **Orthogonal to a component's `variant`**: it recolours the accent the surface draws from (focus ring, tinted fill, selection) without changing its variant. Resolved via `data-tint` attribute selectors in CSS (tokens-only, ADR-0003). - `trailingIcon`: `ReactNode`. Trailing glyph, forwarded to {@link Link}. - `variant`: `ButtonVariant | undefined`. Glass style, delegated to {@link Link}. Defaults to `"automatic"`. ## SwiftUI mapping - ``ShareLink(item:)`` → ``item` (required)` (direct): A value that parses as an absolute URL → payload `url`; anything else → payload `text`. A ShareLink with nothing to share has no meaning. - ``ShareLink(subject:)`` → ``subject`` (direct): → payload `title` (e.g. the pre-filled subject line of an email share). - ``ShareLink(message:)`` → ``message`` (direct): → payload `text`. Appended to a non-URL `item` (`"{message}\n\n{item}"`) rather than overwriting it — the required `item` content never vanishes from the share sheet. - ``ShareLink { label }`` → ``children` (node) + `leadingIcon` / `trailingIcon`` (direct): children role: `label` (token parity — ShareLink's text renders through Button; no `labelProps` seam, ADR-0028 rule 3 / charter §2 rule 5). Omit for the default "Share" + share-glyph label. - ``.buttonStyle(_:)`` → ``variant`` (direct): `ButtonVariant`, forwarded to Button. - ``.controlSize(_:)`` → ``size`` (direct): `small | regular | large`, the truthful `ButtonSize` re-export (charter §7 rule 4, composition-wrapper exception). - ``.tint(color)`` → ``tint`` (direct): Restricted `LiquidColor` palette; recolours the prominent/translucent surfaces only. - ``.disabled(_:)`` → ``disabled`` (direct): Shape N: native `