<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# ShareButton

A button that shares a link: through the system's share sheet where there is one (phones, Safari), and by copying it where there is not, when it says "Link copied" for two seconds and screen readers hear it once. It shares the page's own address unless given `url`. When neither works, it says for two seconds which the browser blocked, "Browser blocked sharing" or, where there is no share sheet, "Browser blocked copying", with the whole of `failedMessage` as its tooltip, and screen readers hear that whole sentence once.

```tsx
import { ShareButton } from "@/components/ouro/share-button/share-button";
```

## Example

```tsx
<ShareButton url={`https://example.com/notes/${note.id}`} title={note.title} />
```

## Use instead when

- Use `CopyButton` instead to copy any text without a share sheet, and the `share()` helper for a share action inside a menu.

## Props

Type: `ShareButtonProps`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Layout only: margins, grid placement (`ms-auto`). Appearance classes warn in development. |
| `copiedLabel` | `string` | `"Link copied"` | What it says, and screen readers hear, when there was no share sheet and the link was copied instead. |
| `failedLabel` | `string` | `"Browser blocked sharing"` when the share sheet refused, "Browser blocked copying" where there is no share sheet | What it says for two seconds when neither sharing nor copying worked: short, so the button keeps its width. |
| `failedMessage` | `string` | `"The browser refused the share and blocked copying the link. Copy the link by hand."` when the share sheet refused, "This browser has no share sheet, and it blocked copying the link. Copy the link by hand." where there is none, or `failedLabel` when only that is given | What screen readers hear, and the button's tooltip says while it shows `failedLabel`, when neither sharing nor copying worked: what happened and what to do instead. |
| `hideLabel` | `boolean` |  | Shows only the icon; the label stays the button's name for screen readers. |
| `label` | `string` | `"Share"` | The button's label, and its name for screen readers with `hideLabel`. |
| `onShare` | `((result: ShareResult) => void)` |  | Called with how the share ended: `shared`, `copied`, `cancelled` or `failed`. |
| `ref` | `Ref<HTMLButtonElement>` |  | Reaches the rendered element. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Control size, as Button's. |
| `text` | `string` |  | A line about the link, where the receiving app takes one. |
| `title` | `string` |  | A title for the link, where the receiving app takes one. |
| `url` | `string` | the page's own address | The address to share. |
| `variant` | `"solid" \| "soft" \| "outline" \| "plain"` | `"outline"` | Visual weight, as Button's. |

## Native attributes

Also accepts the attributes in React's `ButtonHTMLAttributes` and `HTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page.

## Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

- `children`: Not a prop. The label is `label`: `<ShareButton label="Share recipe" />`.
- `href`: Not a prop. The address is `url`: `<ShareButton url={link} />`.
- `onClick`: Not a prop. ShareButton shares on click itself; to react to it, pass `onShare`.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`). Your classes always win over Ouro UI's: ShareButton merges `className` last with `cn` (tailwind-merge), so a class that conflicts with its own replaces it.[^layout-classes]

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: set alignment on a parent element.

[^layout-classes]: test:registry/ouro/components/ouro/share-button/share-button.test.tsx::ShareButton > forwards a ref, takes button attributes, and lets app layout classes win verify:testExists(registry/ouro/components/ouro/share-button/share-button.test.tsx::ShareButton > forwards a ref, takes button attributes, and lets app layout classes win)