Component catalog
Browse the public controls by interaction purpose. Every result links to generated API facts, accessibility behavior, source, and exhaustive stories.
Browse the public controls by interaction purpose. Every result links to generated API facts, accessibility behavior, source, and exhaustive stories.
A user-invokable control that shares content — the SwiftUI ShareLink.
import { ShareLink } from "@liquidify/react/share-link"| Prop | Type | Default | Description |
|---|---|---|---|
| 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 required | string | — | 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<HTMLButtonElement>) => 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<HTMLButtonElement> | 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<HTMLElement>`. 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"`. |
ShareLink supports the documented keyboard interactions below.
| Name | Value |
|---|---|
| --lq-button-fill | var(--lq-color-action-primary)var(--lq-glass-fill-0)transparentlight-dark( var(--lq-color-system-red-default-light, var(--lq-color-action-destructive)), var(--lq-color-system-red-default-dark, var(--lq-color-action-destructive)) )color-mix(in srgb, var(--lq-tint-current, var(--lq-color-action-primary)) 40%, transparent)color-mix( in srgb, light-dark(var(--lq-color-system-gray-1-default-light), var(--lq-color-system-gray-1-default-dark)) 40%, transparent )var(--lq-tint-current, var(--lq-color-accent))light-dark( var(--lq-color-system-gray-1-default-light, var(--lq-color-accent)), var(--lq-color-system-gray-1-default-dark, var(--lq-color-accent)) )var(--lq-alert-control-fill)var(--lq-alert-control-fill-hover)var(--lq-dialog-control-fill)var(--lq-dialog-control-fill-hover) |
| --lq-button-label | var(--lq-color-on-action-primary)light-dark( var(--lq-color-system-blue-default-light, var(--lq-color-accent)), var(--lq-color-system-blue-default-dark, var(--lq-color-accent)) )light-dark(var(--lq-color-label-primary-light), var(--lq-color-label-primary-dark))light-dark( var(--lq-color-system-red-default-light, var(--lq-color-action-destructive)), var(--lq-color-system-red-default-dark, var(--lq-color-action-destructive)) )var(--lq-tint-current, var(--lq-color-action-primary))light-dark( var(--lq-color-system-gray-1-default-light), var(--lq-color-system-gray-1-default-dark) )var(--lq-banner-accent)light-dark(var(--lq-color-label-secondary-light), var(--lq-color-label-secondary-dark)) |
| --lq-button-ring | var(--lq-button-fill)var(--lq-tint-current, var(--lq-color-action-primary))light-dark(var(--lq-color-system-gray-1-default-light), var(--lq-color-system-gray-1-default-dark)) |
| --lq-tint-current | var(--lq-color-accent)light-dark( var(--lq-color-system-blue-default-light, var(--lq-color-accent)), var(--lq-color-system-blue-default-dark, var(--lq-color-accent)) )light-dark( var(--lq-color-system-brown-default-light, var(--lq-color-accent)), var(--lq-color-system-brown-default-dark, var(--lq-color-accent)) )light-dark( var(--lq-color-system-cyan-default-light, var(--lq-color-accent)), var(--lq-color-system-cyan-default-dark, var(--lq-color-accent)) )light-dark( var(--lq-color-system-green-default-light, var(--lq-color-accent)), var(--lq-color-system-green-default-dark, var(--lq-color-accent)) )light-dark( var(--lq-color-system-indigo-default-light, var(--lq-color-accent)), var(--lq-color-system-indigo-default-dark, var(--lq-color-accent)) )light-dark( var(--lq-color-system-mint-default-light, var(--lq-color-accent)), var(--lq-color-system-mint-default-dark, var(--lq-color-accent)) )light-dark( var(--lq-color-system-orange-default-light, var(--lq-color-accent)), var(--lq-color-system-orange-default-dark, var(--lq-color-accent)) )light-dark( var(--lq-color-system-pink-default-light, var(--lq-color-accent)), var(--lq-color-system-pink-default-dark, var(--lq-color-accent)) )light-dark( var(--lq-color-system-purple-default-light, var(--lq-color-accent)), var(--lq-color-system-purple-default-dark, var(--lq-color-accent)) )light-dark( var(--lq-color-system-red-default-light, var(--lq-color-accent)), var(--lq-color-system-red-default-dark, var(--lq-color-accent)) )light-dark( var(--lq-color-system-teal-default-light, var(--lq-color-accent)), var(--lq-color-system-teal-default-dark, var(--lq-color-accent)) ) |